暗黑模式

暗黑模式由主题系统的 darkMode 统一控制，与多主题共用同一套令牌：切换模式时，库会重新计算当前主题的暗色调色板，同步写入全局 $u.color 与 CSS 变量，组件无需感知模式即可自动变色。内置的官方蓝主题已自带暗色板，开箱即用。

三种模式

取值	说明
`'auto'`	跟随系统主题，系统切到深色时自动进入暗黑态
`'light'`	强制亮色，忽略系统设置
`'dark'`	强制暗黑

默认值为 'light'（即 config.defaultDarkMode）。

安装时配置

在 app.use 的 theme 选项里指定默认模式：

app.use(uViewProX, {
    theme: {
        themes: themes,          // 可选：注册多套主题
        defaultTheme: 'purple',  // 可选：默认主题
        defaultDarkMode: 'auto', // 默认暗黑模式
        isForce: false           // true 时忽略本地已保存的选择
    }
})

defaultDarkMode 也属于全局配置字段，可放到通用 config 里：

app.use(uViewProX, {
    config: {
        defaultDarkMode: 'dark'
    }
})

初始模式优先级

本地已保存的选择 > theme.defaultDarkMode / config.defaultDarkMode > 内置默认 'light'。当 isForce: true 时，theme.defaultDarkMode 优先级最高，本地已保存值被忽略。

运行时切换

用 useTheme 在页面里切换与读取状态：

import { useTheme } from '@/uni_modules/uview-pro-x'

const { darkMode, setDarkMode, toggleDarkMode, isInDarkMode } = useTheme()

// 跟随系统
setDarkMode('auto')
// 强制暗黑
setDarkMode('dark')
// 在当前基础上切换（dark ↔ light）
toggleDarkMode()
// 读取当前是否处于暗黑态
const dark = isInDarkMode()

成员	类型	说明
`darkMode`	`Ref<DarkMode>`	当前模式设置（`'auto'` / `'light'` / `'dark'`）
`setDarkMode`	`(mode: DarkMode) => void`	设置模式并持久化
`getDarkMode`	`() => DarkMode`	读取当前模式设置
`isInDarkMode`	`() => boolean`	当前是否处于暗黑态（`'auto'` 时按系统判定）
`toggleDarkMode`	`() => void`	在亮 / 暗之间切换

isInDarkMode() 的判定规则：'dark' 恒为 true，'light' 恒为 false，'auto' 时 App 端读 uni.getDeviceInfo().osTheme，其他端读 uni.getAppBaseInfo().hostTheme。

模式设置会持久化到本地存储（键 uview-pro-x-dark-mode），下次启动自动恢复。

暗色板如何生成

每套主题可显式提供 darkColor；未提供的字段按下述规则自动生成：

结构色令牌：直接取内置暗色板对应值，不参与混合。包含 bgColor / bgWhite / bgGrayLight / bgGrayDark / bgBlack / borderColor / lightColor / mainColor / contentColor / tipsColor / whiteColor / blackColor / dividerColor / maskColor / shadowColor。
类型色令牌（primary / success / warning / error / info 及其 Dark / Disabled / Light 派生）：以亮色值与内置暗色回退值按 0.6 比例混合，得到既保留品牌感又适配深色背景的暗色变体。

内置暗色板（节选）：

令牌	暗色值
`primary`	`#8ab4ff`
`success`	`#4ade80`
`warning`	`#fbbf24`
`error`	`#ff6b6b`
`info`	`#a0a7b8`
`mainColor`	`#f5f6f7`
`bgColor`	`#111827`
`borderColor`	`#3a4251`

若要精确控制暗色，显式提供 darkColor，逐字段覆盖自动生成值：

{
    name: 'purple',
    label: '霞光紫',
    color: { primary: '#7c3aed' },
    darkColor: { primary: '#c4b5fd' } // 暗色下单独指定
}

平台联动

App 端：切换模式时会同步调用 uni.setAppTheme，使原生页面背景与导航栏跟随切换，避免闪白 / 闪黑。
'auto' 模式：库会注册系统主题监听——App 端 uni.onOsThemeChange、其他端 uni.onHostThemeChange，系统主题变化时自动重算调色板（监听仅注册一次）。

页面侧用法

组件样式会自动读取令牌，页面自定义样式同样可通过 CSS 变量适配暗黑：

vue

<template>
    <view class="card">
        <text class="title">{{ title }}</text>
    </view>
</template>

<style scoped>
.card {
    background-color: var(--u-bg-white);
    color: var(--u-main-color);
}
</style>

需要按模式分支时，可在合适的时机（如 onShow）调用 isInDarkMode() 判断，再为节点绑定类名；主题生效时会额外生成模式标记变量 --u-theme-mode，取值为 light / dark。

注意事项

暗色变体由混合自动生成，并非精确设计值；对暗色有精确要求时请显式提供 darkColor。
'auto' 模式下 isInDarkMode() 依赖系统主题接口（App 端 uni.getDeviceInfo、其他端 uni.getAppBaseInfo），接口不可用时按亮色处理。
App 端原生背景 / 导航栏联动依赖 uni.setAppTheme，切换模式后需保证该方法被调用（setDarkMode 内部已处理）。
暗黑模式与主题选择分别持久化（键 uview-pro-x-dark-mode 与 uview-pro-x-theme），互不影响。
toggleDarkMode() 在当前为 'auto' 时按「非 dark 即切换为 dark」处理，即 'auto' → 'dark'。

暗黑模式 ​

三种模式 ​

安装时配置 ​

运行时切换 ​

暗色板如何生成 ​

平台联动 ​

页面侧用法 ​

注意事项 ​