ConfigProvider

17:06

Description

Configuration injection component: injects the current theme's CSS variables onto the root node and calls the global setTheme / setDarkMode / setLocale on mount and whenever the props change. Place it at the app or page root so children and the component library share one theme, dark mode and locale.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Wrapping content injects the theme CSS variables so children can use theme classes directly.

View source

<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>

Theme Injection (current-theme)

current-theme switches the theme name; initialization and changes call the global setTheme (affects the whole app).

View source

<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)

dark-mode controls light / dark / auto.

View source

<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>

Locale (current-locale)

current-locale switches the locale name (e.g. zh-CN / en-US); the whole app follows.

View source

<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>

Events

theme-change / mode-change fire when the theme or dark mode changes; the latest record is shown below.

View source

<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

Property	Description	Type	Default	Version
customStyle	Custom style for the root node	String	''	-
customClass	Custom class for the root node	String	''	-
darkMode	Dark mode: light / dark / auto. Defaults to empty (no override)	String	''	-
currentTheme	Current theme name. Defaults to empty	String	''	-
currentLocale	Current locale name. Defaults to empty	String	''	-

Events

Event	Description	Params	Version
theme-change	Emitted when the global theme changes, carrying the new theme name	themeName: string	-
mode-change	Emitted when the global dark mode changes, carrying the new mode	mode: string	-

Slots

Slot	Description	Version
default	Content mounted under the configuration root	-

Notes

1. currentTheme / darkMode / currentLocale all call global setters and affect the whole app rather than a local scope; mounting several providers with different values makes them overwrite each other.
2. darkMode accepts only light / dark / auto; any other value is ignored. An empty string leaves the current mode untouched.
3. On mount the component compares the props with the global state and only writes when they differ, avoiding redundant updates.
4. theme-change / mode-change are driven by global state changes; no initial event is emitted on first mount (both old and new values must exist).
5. Theme variables are injected through the root node's style, so children can use var(--u-*) directly; library components still read the global theme.
6. Changing currentLocale emits no event; read the active locale through useLocale after switching.