uView Pro X

简体中文

English

简体中文

English

主题

ConfigProvider 配置容器 ​

17:06

说明 ​

配置注入组件：把当前主题的 CSS 变量下发到根节点，并在初始化与属性变化时调用全局 setTheme / setDarkMode / setLocale。适合放在应用或页面根部，让子内容与组件库共用同一套主题、暗黑模式与语言。

兼容性 ​

平台支持情况
App✅ 支持
H5✅ 支持
微信小程序✅ 支持

示例 ​

基础用法 ​

包裹子内容即注入当前主题的 CSS 变量，子内容可直接使用主题变量类。

查看源码
vue
<template>
    <ux-config-provider>
        <view class="config-provider-banner">
            <text>主题变量已注入：背景色与文字色随全局主题联动</text>
        </view>
    </ux-config-provider>
</template>

<style scoped>
.config-provider-banner {
    padding: 12px 15px;
    border-radius: 6px;
    background-color: var(--u-type-primary-light, #ecf5ff);
    color: var(--u-type-primary, #2979ff);
}
</style>

主题注入 current-theme ​

current-theme 切换主题名称，初始化与变化都会调用全局 setTheme（整个应用生效）。

查看源码
vue
<template>
    <ux-config-provider :current-theme="currentTheme">
        <view class="config-provider-row">
            <ux-button custom-class="config-provider-item" type="primary" size="small" shape="round" text="霞光紫（默认）" @click="switchTheme('purple')" />
            <ux-button custom-class="config-provider-item" type="success" size="small" shape="round" text="清翠绿" @click="switchTheme('green')" />
            <ux-button custom-class="config-provider-item" type="warning" size="small" shape="round" text="暖阳橙" @click="switchTheme('orange')" />
        </view>
    </ux-config-provider>
</template>

<script setup lang="uts">
import { useTheme } from '@/uni_modules/uview-pro-x';

const { getCurrentTheme } = useTheme();

const themeInfo = getCurrentTheme();
const currentTheme = ref(themeInfo != null ? themeInfo.name : '');

const switchTheme = (name: string) => {
    currentTheme.value = name;
};
</script>

<style scoped>
.config-provider-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.config-provider-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

暗黑模式 dark-mode ​

dark-mode 控制 light / dark / auto 三种模式。

查看源码
vue
<template>
    <ux-config-provider :dark-mode="currentMode">
        <view class="config-provider-row">
            <ux-button custom-class="config-provider-item" type="primary" size="small" shape="round" text="亮色" @click="switchMode('light')" />
            <ux-button custom-class="config-provider-item" type="primary" size="small" shape="round" text="暗黑" @click="switchMode('dark')" />
            <ux-button custom-class="config-provider-item" type="primary" size="small" shape="round" text="自动" @click="switchMode('auto')" />
        </view>
    </ux-config-provider>
</template>

<script setup lang="uts">
import { useTheme } from '@/uni_modules/uview-pro-x';

const { getDarkMode } = useTheme();

const currentMode = ref<string>(getDarkMode());

const switchMode = (mode: string) => {
    currentMode.value = mode;
};
</script>

<style scoped>
.config-provider-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.config-provider-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

国际化 current-locale ​

current-locale 切换语言名称（如 zh-CN / en-US），整个应用的文案随之切换。

查看源码
vue
<template>
    <ux-config-provider :current-locale="currentLocale">
        <view class="config-provider-row">
            <ux-button custom-class="config-provider-item" type="primary" size="small" shape="round" text="简体中文" @click="switchLocale('zh-CN')" />
            <ux-button custom-class="config-provider-item" type="primary" size="small" shape="round" text="English" @click="switchLocale('en-US')" />
        </view>
    </ux-config-provider>
</template>

<script setup lang="uts">
import { useLocale } from '@/uni_modules/uview-pro-x';

const { getCurrentLocale } = useLocale();

const localeInfo = getCurrentLocale();
const currentLocale = ref(localeInfo != null ? localeInfo.name : '');

const switchLocale = (name: string) => {
    currentLocale.value = name;
};
</script>

<style scoped>
.config-provider-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.config-provider-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

事件回调 ​

主题或暗黑模式变化时触发 theme-change / mode-change，下方便是最新事件记录。

查看源码
vue
<template>
    <ux-config-provider
        :current-theme="currentTheme"
        :dark-mode="currentMode"
        @theme-change="onThemeChange"
        @mode-change="onModeChange"
    >
        <view class="config-provider-events">
            <text class="config-provider-event-line">{{ eventText }}</text>
        </view>
    </ux-config-provider>
</template>

<script setup lang="uts">
import { useTheme } from '@/uni_modules/uview-pro-x';

const { getCurrentTheme, getDarkMode } = useTheme();

const themeInfo = getCurrentTheme();
const currentTheme = ref(themeInfo != null ? themeInfo.name : '');
const currentMode = ref<string>(getDarkMode());

const eventText = ref('暂无事件');

const onThemeChange = (name: string) => {
    eventText.value = 'theme-change：' + name;
};

const onModeChange = (mode: string) => {
    eventText.value = 'mode-change：' + mode;
};
</script>

<style scoped>
.config-provider-events {
    display: flex;
    flex-direction: column;
}
.config-provider-event-line {
    font-size: 13px;
    color: #606266;
    line-height: 1.8;
}
</style>

API ​

Props ​

属性说明类型默认值版本
customStyle自定义根节点样式String''-
customClass自定义根节点样式类String''-
darkMode暗黑模式，可选 'light' / 'dark' / 'auto'，默认空String''-
currentTheme当前主题名称，默认空String''-
currentLocale国际化当前语言名称，默认空String''-

Events ​

事件名说明回调参数版本
theme-change主题变化时触发，携带新主题名themeName: string-
mode-change暗黑模式变化时触发，携带新模式名mode: string-

Slots ​

插槽名说明版本
default需要挂载到配置顶点的子内容-

注意事项 ​

  1. currentTheme / darkMode / currentLocale 都调用全局 setter，作用于整个应用而非局部作用域；多处挂载且取值不同时会互相覆盖。
  2. darkMode 只接受 light / dark / auto，其他值被忽略；空字符串表示不干预当前模式。
  3. 挂载时会先比对全局状态，只有属性值与当前状态不一致才写入，避免重复设置。
  4. theme-change / mode-change 由全局状态变化触发；首次挂载不会补发初始值（需要同时存在新旧值才派发）。
  5. 主题变量通过根节点 style 下发，子内容可直接使用 var(--u-*)；组件库组件自身仍从全局主题取值。
  6. 仅修改 currentLocale 不会触发事件，语言变化后可直接通过 useLocale 读取当前语言。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5