全局配置

组件库的全局配置集中在一个响应式 config 对象上，安装时可传入，运行时可通过 $u.config 读取、$u.setConfig 修改。它管理单位、默认主题、默认语言、调试模式与组件级默认值等。

安装时配置

在 main.uts 的 app.use 里通过 config 选项设置：

app.use(uViewProX, {
    config: {
        unit: 'px',
        debugMode: true,
        componentProps: {
            'ux-back-top': { fontSize: '19px' }
        }
    }
})

可配置字段

字段	类型	默认值	说明
`version`	`string`	库版本	版本号（冗余字段）
`type`	`string[]`	`['primary','success','error','warning','info']`	类型令牌列表，用于 CSS 变量前缀判定
`defaultTheme`	`string`	`'uviewpro'`	默认主题名称
`defaultDarkMode`	`DarkMode`	`'light'`	默认暗黑模式
`defaultLocale`	`string`	`'zh-CN'`	默认语言
`debugMode`	`boolean \| DebugMode \| DebugMode[]`	`false`	调试模式开关 / 级别（`log` / `warn` / `error` / `info`）
`unit`	`string`	`'px'`	单位，供尺寸类属性拼接
`componentProps`	`UTSJSONObject`	`{}`	组件级默认值覆盖

空值不覆盖

setConfig 对空值（空字符串、空数组、null 等）保持默认值不动，因此只传需要改的字段即可，无需补齐全部键。

运行时读取与修改

通过全局工具对象 $u 访问：

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

// 读取
console.log($u.config.unit)          // 'px'
console.log($u.config.defaultTheme)  // 'uviewpro'

// 修改（原位合并，空值不覆盖）
$u.setConfig({ unit: 'rpx' })

组件级默认值

componentProps 用于在不改组件源码的前提下，为某个组件的 prop 设定项目级默认值，键为组件名（ux- 前缀），值为该组件 props 的部分字段：

app.use(uViewProX, {
    config: {
        componentProps: {
            'ux-back-top': { fontSize: '19px' },
            'ux-button': { size: 'large' }
        }
    }
})

组件取值的优先级为：组件调用处传入的 prop > componentProps 配置 > 组件自身 withDefaults 默认值。因此 componentProps 只影响未显式传值的调用。

注意事项

config 是响应式对象，运行时修改 $u.config 或调用 $u.setConfig 会即时生效；但已渲染组件中由默认值派生的内部状态不一定回溯，建议在应用启动阶段完成配置。
type 参与 CSS 变量前缀判定：以其中任一值为前缀的令牌会生成 --u-type-* 变量，改动它会影响主题变量命名，非必要不要修改。
componentProps 为深合并：多次调用会逐层合并，不会整体替换已有配置。
unit 影响尺寸拼接结果（如 addUnit），切换为 rpx 后所有依赖该单位的默认尺寸随之变化，需评估布局。
defaultTheme / defaultDarkMode / defaultLocale 与安装选项中的 theme / locale 存在交叠，后者在初始化时会覆盖对应配置项，二者择一维护即可。

全局配置 ​

安装时配置 ​

可配置字段 ​

运行时读取与修改 ​

组件级默认值 ​