# 自定义主题

uview-plus目前可以自定主题色，字体颜色，边框颜色等，所有组件内部的样式，都基于同一套主题，比如您修改了primary主题色，所有用到了primary颜色 的组件都会受影响。

# 教程

1. 可以在打开的颜色拾取器中输入或者选择颜色，再点"确定"按钮即可。
2. 老项目若已经在uni.scss中手写覆盖$u-primary、$u-main-color等变量，升级后无需先删除这些覆盖。
3. 新版本会把这些旧$u-*值桥接到light主题对应的--up-*变量。
4. 请继续保留@import 'uview-plus/theme.scss';，不要再下载并替换整份内置主题文件。
5. 如果需要运行时切换深浅色，请配合暗黑模式文档中的setTheme / setThemePreference使用。
6. 如果需要一套完全自定义的dark主题，请不要只依赖旧$u-*变量文件，需额外按CSS变量方案定制。

# 旧项目兼容写法

如果你原来就是在uni.scss里手写$u-*变量，升级后推荐保持下面这种结构：

/* uni.scss */
$u-primary: #3b82f6;
$u-main-color: #1f2937;
$u-border-color: #d0d5dd;

@import 'uview-plus/theme.scss';

请注意：

1. 旧$u-*覆盖请写在@import 'uview-plus/theme.scss';之前，这样桥接层才能拿到你最终定义的值。
2. uni.scss里仍然只建议放变量，不要把uview-plus/index.scss这类完整样式文件引进来。
3. 这套兼容只负责light主题；如果你又调用了setConfig({ color })，运行时显式颜色配置会优先覆盖bridge结果。

# 主题来源与优先级

从 3.8+ 开始，uview-plus 的主题要按三层来理解：

1. theme.json 这是 uni-app 的声明式默认主题入口，主要通过 pages.json 里的 @变量名 参与页面配置。

2. --up-* / --u-* CSS变量 这是组件样式、页面背景、语义色的核心主题变量层。

3. uni.$u.setTheme() / uni.$u.setThemePreference() / setConfig({ color }) 这是 uview-plus 的运行时主题系统，用于跟随系统、手动切换、记忆偏好，以及同步原生 UI。

请注意：

• 页面初始默认值可以来自 theme.json
• 一旦 uview-plus 运行时主题开始同步，导航栏、背景色、tabBar 的最终效果以当前运行时主题结果为准
• 导航栏推荐定制入口是 up-navbar-bg-color / --up-navbar-bg-color

# 3.8+ 升级提醒

如果你是旧项目升级，请先记住下面几条：

1. 新版本主题体系已经迁移到 CSS变量为主，不再等同于旧版“下载整份 SCSS 主题文件后整体替换”的心智。
2. 旧 uni.scss 中手写的 $u-* 仍兼容，但只桥接到 light 主题。
3. dark 主题不会从旧 $u-* 自动生成。
4. 如果业务又调用了 setConfig({ color })，显式运行时改色优先级高于旧 bridge。
5. 旧项目必须继续保留 @import 'uview-plus/theme.scss';，并且要把 $u-* 变量写在它之前。

# 主题色

目前有五个主题色，每个主题色又分别有对应的light(淡色)、dark(深色)、disabled(禁止状态时的颜色)：

# 文字颜色

内置的文字颜色有：主要文字、常规文字，次要文字、占位文字颜色，如需更详细的，详见：Color 色彩章节。

# 边框颜色

uview-plus所有组件边框相关的(特别说明的除外)，用的都是这一个颜色。

# 背景颜色

这个颜色是uview-plus推荐的背景色，目前内置组件中使用的场景不多。

# Input边框颜色

此颜色用于在up-input组件显示边框时的边框颜色。