# 自定义主题

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

# 教程

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

# VUE / NVUE 修改主题变量的方法

从 3.8+ 开始，请把 vue 和 nvue 分开理解，不要再按同一种方式改主题变量。

# VUE / UVUE

.vue / .uvue 页面可以直接覆盖 CSS 变量。推荐在 App.vue 首行引入 uview-plus/index.scss 后，再在同一个文件里覆盖 --up-* 变量。

<style lang="scss">
@import "uview-plus/index.scss";

:root,
page,
body,
[data-up-theme='light'] {
  --up-primary: #1abc9c;
  --up-light-primary: #1abc9c;
  --up-navbar-bg-color: #1abc9c;
}
</style>

请注意：

1. vue 下推荐直接改 --up-* CSS变量，不再推荐通过下载整份 SCSS 主题文件整体替换。
2. uni.scss 里的 $u-* 仍然只作为旧项目兼容桥接使用，不是新主题方案的主入口。
3. 如果业务同时又调用了 setConfig({ color })，运行时显式颜色配置仍会优先覆盖 bridge 结果。

# NVUE

.nvue 不支持按 vue 的方式直接依赖 CSS 变量覆盖主题色。nvue 下请使用 setConfig({ color }) 配置运行时颜色。

import { setConfig } from 'uview-plus'

setConfig({
  color: {
    primary: '#1abc9c',
    success: '#18b566',
    warning: '#f59e0b',
    error: '#ef4444',
    info: '#909399'
  }
})

请注意：

1. nvue 下不要把“在 App.vue 或 uni.scss 覆盖 CSS变量”当成主要改色方式。
2. nvue 组件运行时取色依赖 setConfig({ color }) 对应的颜色映射。
3. 如果项目同时存在 nvue 页面，请继续按 Root 根组件 文档启用 UniUpRoot，否则页面主题能力可能报错或白屏。

# 旧项目兼容写法

如果你原来就是在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(禁止状态时的颜色)：

对应的 CSS 变量为 --up-primary、--up-primary-dark、--up-primary-disabled、--up-primary-light，其余语义色同理。以上为light主题下的默认值，dark主题另有一套取值，详见 暗黑模式。

# 文字颜色

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

# 边框颜色

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

# 背景颜色

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

# Input边框颜色

此颜色用于在up-input组件显示边框时的边框颜色，未单独设置时回退到--up-border-color。