wot-ui 暗色主题失效:三层变量与小程序样式隔离
把 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,计算样式却没变,原因就在这里。
三个处理顺序:
- 优先改变量。组件已经把背景、文字、边框暴露成 CSS 变量,变量会沿树继承,不受组件边界影响。
- 需要单点覆盖时,用组件提供的
custom-class或custom-style,不要直接选内部结构。 - 必须跨组件写选择器时,再评估
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 链都落在正确的根节点上;最后用构建产物和计算样式验证,而不是只看源码里有没有那条规则。前端相关的其他排错记录可以继续看 前端开发。
评论
还没有评论,来说两句吧