wot-ui 暗色主题失效:三层变量与小程序样式隔离

2026-11-19 前端开发 有希 40 次瀏覽

把 wd-config-provider 的 theme 改成 dark,常见结果是按钮、单元格变暗了,页面背景仍然发白,搜索框反而变成一条黑带。这不是一个开关没打开,而是三个层各自失效:组件主题变量、业务页面色板、小程序原生外壳。下面按现象拆开。

先把“暗色”拆成三层

Wot UI 的 theme="dark" 只负责它包裹范围内的 Wot 组件。页面背景、正文颜色、theme.json 控制的原生导航栏,都不在这个范围内。

层谁在控制典型载体失效后的现象
组件主题Wot UI 的 --wot-* 变量.wot-theme-dark 根节点单元格、按钮仍是浅色
业务页面自己的 --app-* 色板page 或页面根节点页面、卡片、文字仍是白底黑字
原生外壳小程序 / H5 的窗口配置app.json、theme.json导航栏、下拉背景不跟随

同时存在两条 class 链:Wot 组件认 .wot-theme-dark,业务样式认自己定义的 .theme-dark。两条链都落在同一个根节点上,但作用对象不同,少一条就会出现“一半暗、一半亮”。

最小复现:按钮变暗了,页面还是白的

先看一个能稳定复现的页面结构:

<template>
  <wd-config-provider theme="dark">
    <view class="page">
      <wd-cell title="账号与安全" value="已登录" />
      <wd-search placeholder="搜索" />
    </view>
  </wd-config-provider>
</template>

这段代码里,wd-cell 会切到暗色,view.page 不会。Wot UI 官方文档写得很明确:ConfigProvider 只影响 Wot 组件自身的主题,不会自动修改页面全局文本色或背景色。页面要单独给背景。

第二个常见问题是组件根本没拿到暗色变量,原因是入口样式没有引入主题文件:

/* App.vue 或全局样式入口,必须放在业务规则之前 */
@use '@wot-ui/ui/styles/theme/index.scss' as *;

page {
  background: #f5f7fa;
}

.wot-theme-dark {
  min-height: 100vh;
  background: #10131a;
}

如果漏掉 @use,组件编译后的 fallback 会直接落到白色。以单元格为例,构建产物是:

.wd-cell {
  background: var(--wot-cell-bg, var(--wot-filled-oppo, var(--wot-base-white, white)));
}

暗色主题里 --wot-filled-oppo 是黑色,浅色主题里是白色。但主题文件没引入时,这两个变量都不存在,最后一层 white 生效。看到“只有部分组件变暗”,先查主题文件,而不是继续加 !important。

第一层:主题变量文件与 page 选择器

主题文件的组织方式值得单独看一眼:

page,
.wot-theme-dark,
.wot-theme-dark .wd-root-portal {
  @include dark.dark-theme-vars;
}

page,
.wot-theme-light,
.wot-theme-light .wd-root-portal {
  @include light.light-theme-vars;
}

page 同时出现在暗色和浅色两组选择器里,而浅色规则在后面。两条规则优先级相同,后出现的覆盖前面的,所以 page 上的 --wot-* 永远偏浅色。暗色变量真正生效的位置,是 ConfigProvider 渲染出来的 .wot-theme-dark 根节点及其子树。

这解释了两个现象:

  • 直接把 --wot-filled-oppo 写在 page 上,组件不一定跟着变,因为组件读取的是离自己更近的 provider 根节点。
  • 页面背景不能只靠 .wot-theme-dark 的花括号包一层,还要保证这个根节点铺满视口;否则 provider 外面露出的仍是 page 的浅色。

业务侧最好定义自己的色板,不要直接复用组件变量名:

page {
  --app-page-bg: #f5f7fa;
  --app-card-bg: #ffffff;
  --app-field-bg: #ffffff;
}

@media (prefers-color-scheme: dark) {
  page {
    --app-page-bg: #10131a;
    --app-card-bg: #1b1f27;
    --app-field-bg: #242a36;
  }
}

.theme-light {
  --app-page-bg: #f5f7fa;
  --app-card-bg: #ffffff;
  --app-field-bg: #ffffff;
}

.theme-dark {
  --app-page-bg: #10131a;
  --app-card-bg: #1b1f27;
  --app-field-bg: #242a36;
}

.theme-light 和 .theme-dark 是应用内手动切换用的,媒体查询是跟随系统用的。两者都写,用户手动选浅色时才能覆盖系统深色。色板可以从现有品牌图里取主色,再用 图片取色工具 对齐,避免暗色下对比度掉得太厉害。

第二层:组件变量的两段式 fallback

Wot 组件的背景几乎都写成两段:

$cell-bg: var(--wot-cell-bg, $filled-oppo) !default;
$cell-group-bg: var(--wot-cell-group-bg, $filled-oppo) !default;

第一段是组件自己的变量,第二段才是主题色。这个设计让“单个组件改背景”和“全局换主题”可以分开,但也带来一个很容易忽略的冲突:业务卡片和组件容器各自设置了背景,最终谁生效取决于元素层级。

例如页面写了一个自定义卡片,内部放 wd-cell-group:

<view class="app-card">
  <wd-cell-group>
    <wd-cell title="消息通知" />
  </wd-cell-group>
</view>

.app-card 在暗色下已经是深色,但 wd-cell-group 仍然按 --wot-cell-group-bg 画白底。正确做法不是去改组件内部节点,而是把变量指到业务色板:

.theme-dark {
  --wot-cell-bg: var(--app-card-bg);
  --wot-cell-group-bg: var(--app-card-bg);
}

这样单元格、分组和自定义卡片共用同一个颜色来源,后续换主题只改一处。

plain 搜索框为什么变成一条黑带

wd-search 的 variant 默认是 plain,不是 filled。plain 模式使用一组独立变量:

$search-plain-bg: var(--wot-search-plain-bg, $filled-oppo) !default;
$search-plain-block-bg: var(--wot-search-plain-block-bg, $filled-oppo) !default;
$search-plain-cover-bg: var(--wot-search-plain-cover-bg, $filled-oppo) !default;

暗色主题里 $filled-oppo 是黑色,所以容器、内容块和覆盖层一起变黑。只改 --wot-search-input-bg 没有用,因为那个变量属于 filled 模式。要同时处理容器和覆盖层:

.theme-dark {
  --wot-search-plain-bg: var(--app-page-bg);
  --wot-search-plain-block-bg: var(--app-field-bg);
  --wot-search-plain-cover-bg: var(--app-field-bg);
  --wot-search-plain-block-border-color: var(--app-border);
}

如果只想改输入区,不改外层容器,就保留 --wot-search-plain-bg;但背景和圆角通常要一起看,否则会出现深色页面上一块纯黑矩形。

第三层:原生导航栏与窗口背景

组件和页面都暗了,导航栏还是白色,说明问题已经不在 CSS 变量里,而在小程序原生外壳。manifest 要同时打开 darkmode,并指定 theme.json:

export default defineManifest({
  h5: {
    darkmode: true,
  },
  'mp-weixin': {
    darkmode: true,
    themeLocation: 'theme.json',
  },
})

theme.json 分别描述浅色和深色下的原生颜色:

{
  "light": {
    "navigationBarBackgroundColor": "#f8f8f8",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f5f7fa"
  },
  "dark": {
    "navigationBarBackgroundColor": "#10131a",
    "navigationBarTextStyle": "white",
    "backgroundColor": "#10131a"
  }
}

构建后检查 app.json 是否真的带上了 "darkmode": true 和 "themeLocation": "theme.json",同时确认 theme.json 被复制到了产物根目录。只在源码里写了配置、没有进产物,是很常见的“看起来配了但没生效”。

这里有一个产品层面的取舍:theme.json 跟随系统主题,不跟随应用内手动选择。用户把系统设成浅色、应用里手动选深色时,JS 变量和页面都变暗,原生导航栏仍然是浅色。想要完全一致,只能改用自定义导航栏,或者在切换时调用平台接口同步导航栏颜色;后者的支持范围要按目标平台单独验证。

在 H5 有效,在小程序里不一定

页面样式里写:

.page {
  :deep(.wd-cell) {
    background: #1b1f27;
  }
}

H5 构建后是普通后代选择器,能命中组件内部节点。小程序构建后,规则虽然在页面 wxss 里,但 .wd-cell 位于自定义组件内部,默认样式隔离会挡住页面选择器。开发者工具里能看到节点和 class,计算样式却没变,原因就在这里。

三个处理顺序:

  1. 优先改变量。组件已经把背景、文字、边框暴露成 CSS 变量,变量会沿树继承,不受组件边界影响。
  2. 需要单点覆盖时,用组件提供的 custom-class 或 custom-style,不要直接选内部结构。
  3. 必须跨组件写选择器时,再评估 styleIsolation: 'shared' 或 addGlobalClass,并逐端回归;根组件开放了样式,不代表嵌套组件也开放。

检查时不要只看源码,直接搜构建产物里的规则。可以用 代码格式化与压缩 把压缩后的 wxss 展开,再对照开发者工具的计算样式,确认“规则存在”和“规则命中”是两件事。

一张排查表

现象先查哪一层验证点修复方向
只有部分 Wot 组件变暗组件主题入口是否 @use 主题文件引入 theme/index.scss
组件正常、页面还是白业务页面provider 根节点是否铺满视口给 .theme-dark 设背景和最小高度
单元格白、外层卡片暗组件变量--wot-cell-bg、--wot-cell-group-bg把变量指向业务色板
搜索框整块发黑plain 变量--wot-search-plain-block-bg 和 cover同时改容器与覆盖层
导航栏不跟随原生外壳app.json 的 darkmode、themeLocation补 theme.json 并确认进产物
:deep 规则不生效样式隔离计算样式与页面 wxss改用变量或 custom-class

常见问题

为什么 page 上的暗色变量总被浅色覆盖? 因为 page 同时匹配暗色和浅色两组规则,浅色规则在后面,后写的赢。暗色变量应放在 provider 根节点上。

theme="dark" 为什么不改页面文字颜色? provider 只给 Wot 组件提供主题上下文,页面文字需要业务样式自己设置 color。

手动深色、系统浅色时导航栏还是白的? theme.json 只响应系统主题。手动切换要另接导航栏接口或自定义导航栏。

升级 Wot UI 后旧变量名还能用吗? v2 的变量名与 v1 不同,升级时按当前版本文档核对;不要沿用旧项目里的 --wot-* 名称。

暗色适配的稳定做法是:先把组件变量、业务色板、原生外壳分开,再确认两条 class 链都落在正确的根节点上;最后用构建产物和计算样式验证,而不是只看源码里有没有那条规则。前端相关的其他排错记录可以继续看 前端开发。

評論

登入後即可參與評論

還沒有評論,來說兩句吧

相關文章