微信小程序自定义组件的样式隔离机制，让不少开发者在做主题切换时习惯性地选择给组件传递class或style属性。这样做虽然直观，但主题一旦涉及多个组件、多个页面，维护成本会迅速上升。CSS变量提供了另一条更轻的路径：把主题值定义在页面根节点，组件内部通过var()按需读取。样式隔离限制的是选择器匹配，并未截断CSS自定义属性的继承。

一、CSS变量与组件样式隔离的关系

微信小程序自定义组件默认启用样式隔离，组件内的节点不会匹配到页面或全局的类选择器。这种隔离让组件样式更安全，但也容易让人误以为所有外部样式都无法进入组件。实际上，CSS自定义属性（变量）的继承机制与选择器匹配是两个独立过程。只要组件节点位于页面根节点的后代树中，定义在page选择器上的--theme-primary等变量就会沿着DOM树向下继承，组件内部的var()可以正常读取。

理解这一点后，主题切换的边界就变得清晰：我们不需要把主题色通过properties传入每个组件，只需要在根节点更新变量值，整棵组件树会自动响应。相比styleIsolation: apply-shared这类直接开放样式穿透的方案，CSS变量的侵入性更低，不会把整套页面样式暴露给组件，仅共享了设计令牌。

不过这有一个前提：组件内部必须主动使用var()消费变量。如果你接手的是一个完全写死颜色值的第三方组件，仅靠CSS变量无法覆盖它内部样式，此时才需要考虑外部类注入或修改组件源码。

二、在页面根节点定义并维护主题变量

推荐的做法是在app.wxss中先定义一套默认变量，保证任何页面即使不主动设置也有可用的主题值。然后在页面根节点通过data-theme属性标记当前主题，属性选择器负责覆盖变量值。示例如下：

/* app.wxss */
page {
  --theme-primary: #3a7afe;
  --theme-bg: #f5f6fa;
  --theme-text: #222;
}
page[data-theme="dark"] {
  --theme-primary: #6ea8fe;
  --theme-bg: #1e1e2f;
  --theme-text: #eee;
}

页面结构里，给最外层的<view>绑定data-theme，而不是依赖page标签。因为page是页面根节点，部分小程序基础库中直接通过setData修改page的属性并不方便，而放在普通<view>上更灵活。

<view class="page" data-theme="{{theme}}">
  <custom-card></custom-card>
  <button bindtap="toggleTheme">切换主题</button>
</view>

定义变量时建议加上完整的主题令牌集合，例如主色、辅助色、背景色、文字色、边框色、圆角、阴影等。变量名保持语义化，避免出现--color1这种模糊命名。后续设计调整时，只需要改app.wxss中的映射关系，不必逐个组件查找替换。

三、组件内部消费CSS变量

组件样式文件里直接使用var()读取变量，同时提供降级默认值。降级值能保证组件在脱离页面根节点变量环境时仍可正常渲染。比如某个组件可能被用在独立分包或不同页面，如果某个页面没有设置page变量，var(--theme-bg, #fff)会回退到白色，不会导致样式崩溃。

/* components/custom-card/custom-card.wxss */
.card {
  background: var(--theme-bg, #fff);
  color: var(--theme-text, #333);
  border: 1px solid var(--theme-primary, #3a7afe);
  border-radius: 8px;
  padding: 24rpx;
}
.card__title {
  color: var(--theme-text, #333);
  font-size: 32rpx;
}

需要特别留意的是，CSS变量只能用于属性值，不能用作选择器或属性名。例如不能写成var(--theme-primary): 1px，也不能在媒体查询条件中使用变量。小程序端的CSS变量兼容性较好，但旧基础库可能对部分场景支持不完整，重要项目建议在真机上做基础库版本验证。

如果组件使用Component构造器，且希望页面级变量一定能传入，可以检查组件options中的styleIsolation。默认isolated不会阻断变量继承，但如果某些基础库版本行为不一致，可以显式设置styleIsolation: 'apply-shared'，让页面样式应用到组件内部。这个设置会同时带来选择器穿透，需要权衡使用。

四、动态切换的完整流程与持久化

主题切换的交互通常由一个按钮触发。页面js中维护当前主题状态，切换时更新data-theme对应的数据，并把新主题写入本地缓存，方便下次启动时恢复。如下：

// pages/home/home.js
Page({
  data: {
    theme: 'light'
  },
  onLoad() {
    const cached = wx.getStorageSync('theme')
    if (cached) {
      this.setData({ theme: cached })
    }
  },
  toggleTheme() {
    const next = this.data.theme === 'light' ? 'dark' : 'light'
    this.setData({ theme: next })
    wx.setStorageSync('theme', next)
  }
})

在这个流程里，setData更新theme后，WXML中的data-theme属性会同步变化，对应的page[data-theme="dark"]选择器立即生效，CSS变量值被覆盖，所有使用这些变量的组件自动重绘。整个过程不需要手动调用组件方法，也不需要向组件传递新的properties。

如果你的页面结构不是从根节点<view>开始，而是分散在多个容器中，还可以把data-theme绑定到每个页面最外层节点。对于tabBar这类原生导航部分，CSS变量无能为力，因为tabBar是原生组件，样式不受页面CSS影响。此时需要结合wx.setTabBarStyle在切换时同步更新原生导航栏的颜色。

五、多主题扩展与工程化建议

当主题不止亮色和暗色两套时，建议把所有主题变量集中到一个独立的theme.wxss文件中，通过@import引入。每个主题定义成一个属性选择器块，例如page[data-theme="green"]、page[data-theme="high-contrast"]。这样新增主题时只需追加一段变量映射，不会影响现有页面逻辑。

/* styles/theme.wxss */
page[data-theme="green"] {
  --theme-primary: #2e8b57;
  --theme-bg: #f0faf3;
  --theme-text: #183a28;
}
page[data-theme="high-contrast"] {
  --theme-primary: #ffcc00;
  --theme-bg: #000;
  --theme-text: #fff;
}

此外，可以在app.js中封装一个主题管理器，统一读取缓存、监听系统暗色模式变化并调用wx.setBackgroundColor、wx.setTabBarStyle等接口。系统暗色模式可以通过wx.getSystemInfoSync().theme获取，也可以使用wx.onThemeChange监听实时变化。将这些逻辑收口后，页面只需调用一个applyTheme(theme)即可。

如果项目中使用了第三方组件库，优先查看它是否已经支持CSS变量定制主题。大部分现代小程序组件库会暴露类似--brand-color的变量，你只需要在页面根节点覆盖这些变量。对于不支持CSS变量的老组件，才考虑通过externalClasses传入外部类名进行局部覆盖。