小程序主题变更需手动同步，因WXML与JS层分离导致:class/:style不响应globalData变化，必须通过CSS变量+根节点class切换，并在各页面onLoad/onShow中主动读取应用。
小程序端无法靠 globalData 或 Vue 响应式自动同步主题变更，必须手动触发样式重载或 class 切换。 因为微信小程序的 WXML 渲染层与 JS 逻辑层分离，globalData.theme 改了，页面不会重新计算 class 或 style 绑定——这是最常被误以为“已生效”却实际失效的点。
为什么小程序端 theme 变更后 UI 不更新
小程序渲染机制决定了：WXML 中的 :class 和 :style 是一次性求值，不监听 JS 对象深层变化；globalData 本身非响应式；watch 在非 Vue 实例上下文（如 App.vue 的 onLaunch）中无效；uni.$on 事件在小程序端虽可用，但若页面未主动绑定或已销毁，监听会丢失。
常见错误现象：
- 调用
changeTheme('dark')后，首页背景色变了，但二级页仍是亮色 - 切换主题后，
uni-button颜色没变，但自定义view有反应 - 开发者工具里看到
globalData.theme === 'dark'，但页面 class 没加theme-dark
必须用 CSS 变量 + class 切换，而非 :style 绑定
小程序组件（尤其是原生组件如 button、input、switch）对运行时 :style 覆盖支持极差，且频繁 diff style 会拖慢渲染。CSS 变量（--primary-color）配合根节点 class（theme-dark）才是稳定解法。
实操建议：
- 在
App.vue的onLaunch和onShow中，根据uni.getStorageSync('theme')给<page>或<view class="app">动态添加 class，例如：document.body.className = 'theme-' + theme（h5）或通过uni.setStorageSync+ 页面 onLoad 读取后设置 data.class - 所有颜色值统一走 CSS 变量：
color: var(--text-color); background-color: var(--bg-color); - 在
uni.scss或全局common/theme.scss中定义两套变量映射：.theme-light { --text-color: #333; --bg-color: #fff; }和.theme-dark { --text-color: #fff; --bg-color: #1a1a1a; } - 避免在组件内写
v-if="theme === 'dark'"控制不同结构，这会让 DOM 差异变大，影响复用和性能
页面级主动同步：onLoad/onShow 中读取并应用
小程序没有全局响应式上下文，每个页面必须自己“认领”当前主题。不能依赖父级传值或 watch，必须在生命周期里显式读取并更新视图状态。
使用场景：
- 用户从设置页返回任意页面时，需立即反映新主题
- 小程序从后台唤醒（onShow），可能系统主题已变（如 iOS 深色模式开关）
实操建议：
- 所有页面的
onLoad和onShow中调用统一函数，例如：this.loadTheme()，内部执行：this.theme = uni.getStorageSync('theme') || 'light'，再触发this.$forceUpdate()或更新 data 中的 class 字符串 - 如果用 Pinia，确保 store 的 state 是响应式的，且页面通过
computed访问：theme: () => useThemeStore().currentTheme（Vue3 + Pinia） - 不要在
onUnload清理主题相关监听——小程序页面卸载后本就不参与渲染，无需解绑
tabBar 和 navigationBar 必须单独处理
小程序的 tabBar 和 navigationBar 是由宿主环境原生渲染的，不受页面 CSS 变量影响，必须调用对应 API 显式设置。
参数差异：
-
uni.setNavigationBarColor：只支持frontColor（'white'或'black'）和backgroundColor（十六进制） -
uni.setTabBarStyle：仅支持color、selectedColor、backgroundColor，不支持渐变或变量 -
uni.setTabBarItem：可单独更新某一项 iconPath / text，适合图标随主题切换（如 sun/moon 图标）
实操建议：
- 把导航栏/TabBar 配置抽成对象，例如：
navConfig.dark = { backgroundColor: '#1a1a1a', frontColor: 'white' } - 在
changeTheme函数末尾统一调用uni.setNavigationBarColor(navConfig[theme])和uni.setTabBarStyle(tabConfig[theme]) - 注意：这些 API 在非 App 端（即小程序）调用是同步生效的，无需 await
真正难的不是“怎么切”，而是“切完之后，有多少地方你根本没想到要通知”。比如自定义弹窗、uView 的 uni-popup、第三方地图插件的控件颜色、canvas 绘制的文字色——它们都不吃 CSS 变量，得各自适配。别指望一次配置全端生效，小程序端的主题同步永远是“手动巡航”，不是“自动驾驶”。
