ConfigProvider 全局配置

为组件提供统一的全局化配置，包括主题、语言、尺寸等。ConfigProvider 使用 Vue 的 provide/inject 机制，为所有子组件提供配置上下文。

基础用法

在应用的最外层使用 ConfigProvider 包裹，所有子组件都会继承配置。

neon-blue

medium

同意用户协议

选项 1

标签二

50%

vue

<template>
  <ExConfigProvider theme="neon-blue" locale="zh-CN" size="medium">
    <ExButton type="primary">主要按钮</ExButton>
    <ExButton type="success">成功按钮</ExButton>
    <ExButton type="warning">警告按钮</ExButton>
  </ExConfigProvider>
  <ExConfigProvider theme="high-contrast" size="small">
    <div style="display: flex; gap: 12px; flex-wrap: wrap;">
      <ExButton type="primary">主要按钮</ExButton>
      <ExButton type="success">成功按钮</ExButton>
      <ExButton type="warning">警告按钮</ExButton>
      <ExButton type="danger">危险按钮</ExButton>
    </div>
  </ExConfigProvider>
</template>

提示

ConfigProvider 会自动将配置传递给所有子组件，无需手动传递 props。

国际化（i18n）

ExUI 统一使用 vue-i18n（Composition API）。你可以选择以下任一方式完成初始化。

推荐方式：使用 ExUI 提供的 createLocaleProvider
手动方式：自行创建 createI18n 并注入 ExUI 的语言包

一、快速开始（推荐）

import { createApp } from 'vue'
import App from './App.vue'
import { createLocaleProvider } from 'vue-ex-ui'

const app = createApp(App)

const i18nProvider = createLocaleProvider({
  locale: 'zh-CN', // 或 'en-US'
  messages: {
    // 可选：合并/覆盖默认文案
    // menu: { search: '查找菜单' }
  }
})

app.use(i18nProvider)
app.mount('#app')

二、手动集成 vue-i18n

import { createApp } from 'vue'
import App from './App.vue'
import { createI18n } from 'vue-i18n'
import { enUS, zhCN } from 'vue-ex-ui'

const app = createApp(App)

const i18n = createI18n({
  legacy: false,
  locale: 'zh-CN',
  messages: {
    'en-US': enUS,
    'zh-CN': zhCN,
  }
})

app.use(i18n)
app.mount('#app')

组件中使用

// 方式A：vue-i18n
import { useI18n } from 'vue-i18n'
const { t, locale } = useI18n()

// 方式B：ExUI 提供的作用域翻译（内部优先代理到 vue-i18n）
import { useLocale } from 'vue-ex-ui'
const { t: tm } = useLocale('menu')

主题切换

通过 theme 属性可以切换不同的主题风格。点击按钮查看不同主题效果。

当前主题：neon-blue

这是一个示例卡片，展示当前主题效果。主题会影响所有子组件的颜色、阴影和视觉效果。

标签成功

vue

<script setup>
import { ref } from 'vue';

const theme = ref('neon-blue');
</script>

<template>
  <ExConfigProvider :theme="theme">
    <ExCard type="primary">
      <h3>当前主题：{{ theme }}</h3>
      <p>这是一个示例卡片</p>
    </ExCard>
  </ExConfigProvider>
</template>

语言切换

通过 locale 属性可以切换界面语言。

暂无数据

vue

<script setup>
import { ref } from 'vue';

const locale = ref('zh-CN');
</script>

<template>
  <ExConfigProvider :locale="locale">
    <ExEmpty />
  </ExConfigProvider>
</template>

全局尺寸

通过 size 属性可以设置所有组件的默认尺寸。点击按钮查看不同尺寸效果。

按钮组件：

输入框：

标签：标签 medium成功警告

vue

<script setup>
import { ref } from 'vue';

const size = ref('medium');
</script>

<template>
  <ExConfigProvider :size="size">
    <ExButton type="primary">按钮</ExButton>
    <ExButton type="success">按钮</ExButton>
  </ExConfigProvider>
</template>

霓虹效果控制

通过 neon-effect 属性可以全局控制霓虹发光效果。禁用后，所有组件的发光效果都会消失。

霓虹卡片

霓虹效果已启用，卡片边缘有发光效果

vue

<script setup>
import { ref } from 'vue';

const neonEffect = ref(true);
</script>

<template>
  <ExConfigProvider :neon-effect="neonEffect">
    <ExButton type="primary">主要按钮</ExButton>
    <ExCard type="primary">霓虹卡片</ExCard>
  </ExConfigProvider>
</template>

动画控制

通过 animation 属性可以全局控制动画效果。禁用后，所有过渡和动画都会被移除。

悬停卡片

鼠标悬停时会有平滑的动画效果

可关闭标签

无障碍支持

ConfigProvider 会自动尊重用户的 prefers-reduced-motion 设置。如果用户在系统中启用了"减少动画"选项，动画会自动禁用。

vue

<script setup>
import { ref } from 'vue';

const animation = ref(true);
</script>

<template>
  <ExConfigProvider :animation="animation">
    <ExButton type="primary">悬停我</ExButton>
    <ExCard hoverable>悬停卡片</ExCard>
  </ExConfigProvider>
</template>

自定义命名空间

通过 namespace 属性可以自定义 CSS 类名前缀。

vue

<template>
  <ExConfigProvider namespace="custom">
    <ExButton type="primary">自定义命名空间按钮</ExButton>
  </ExConfigProvider>
</template>

自定义 z-index

通过 z-index 属性可以自定义组件的 z-index 基础值。

vue

<template>
  <ExConfigProvider :z-index="2000">
    <ExButton type="primary">z-index 基础值为 2000</ExButton>
  </ExConfigProvider>
</template>

综合演示

一个完整的示例，展示如何组合使用多个配置选项。

🎛️ 配置控制面板

主题：

尺寸：

📱 效果预览

标签成功

实时预览

上面的演示是完全交互式的，你可以实时调整配置并查看效果。所有配置都会立即应用到子组件。

嵌套使用

ConfigProvider 支持嵌套使用，内层配置会覆盖外层配置。

外层配置：霓虹蓝主题 + 中等尺寸

外层标签

内层配置：霓虹粉主题 + 小尺寸（覆盖外层）

内层标签

vue

<template>
  <ExConfigProvider theme="neon-blue" size="medium">
    <ExButton type="primary">外层配置</ExButton>

    <ExConfigProvider theme="neon-pink" size="small">
      <ExButton type="primary">内层配置覆盖</ExButton>
    </ExConfigProvider>
  </ExConfigProvider>
</template>

实际应用场景

一个完整的游戏应用示例，展示如何在实际项目中使用 ConfigProvider。

🎮 游戏大厅

欢迎回来，玩家！

1,250

总胜场

85%

胜率

Lv.50

等级

快速操作

应用场景

这个示例展示了如何在应用中使用 ConfigProvider 来统一管理主题、尺寸等配置。所有组件都会自动继承这些配置，无需手动传递 props。

组合式 API

ConfigProvider 提供了一系列组合式 API，方便在组件中使用配置。

vue

<script setup>
import {
  useConfig,
  useTheme,
  useGlobalSize,
  useComponentSize,
  useNeonEffect,
  useAnimation,
  useNamespace,
  useZIndex,
} from 'vue-ex-ui';

// 获取完整配置
const config = useConfig();

// 获取主题
const theme = useTheme();

// 获取全局尺寸
const globalSize = useGlobalSize();

// 获取组件尺寸（支持组件级别覆盖）
const componentSize = useComponentSize(props.size);

// 获取霓虹效果开关
const neonEffect = useNeonEffect();

// 获取动画开关
const animation = useAnimation();

// 获取命名空间工具
const { namespace, b, e, m, em, is } = useNamespace('button');

// 获取 z-index
const zIndex = useZIndex(10); // 基础值 + 10
</script>

useNamespace 示例

useNamespace 提供了 BEM 命名规范的工具函数：

vue

<script setup>
import { useNamespace } from 'vue-ex-ui';

const ns = useNamespace('button');

// b() -> 'ex-button'
// e('icon') -> 'ex-button__icon'
// m('primary') -> 'ex-button--primary'
// em('icon', 'left') -> 'ex-button__icon--left'
// is('disabled') -> 'is-disabled'
</script>

<template>
  <button :class="[ns.b(), ns.m('primary'), ns.is('disabled', disabled)]">
    <span :class="ns.e('icon')">Icon</span>
    <span :class="ns.e('text')">Text</span>
  </button>
</template>

API

ConfigProvider Props

属性	说明	类型	默认值
`theme`	主题	`'neon-blue' \| 'neon-pink' \| 'dark' \| 'high-contrast'`	`'neon-blue'`
`locale`	语言	`'zh-CN' \| 'en-US'`	`'en-US'`
`size`	全局组件尺寸	`'small' \| 'medium' \| 'large'`	`'medium'`
`neon-effect`	是否启用霓虹效果	`boolean`	`true`
`animation`	是否启用动画	`boolean`	`true`
`namespace`	CSS 类名前缀	`string`	`'ex'`
`z-index`	z-index 基础值	`number`	`1000`

ConfigProvider Slots

插槽名	说明
`default`	配置作用的内容

Composables

useConfig()

获取完整的配置上下文。

typescript

function useConfig(): ConfigContext;

useTheme()

获取当前主题。

typescript

function useTheme(): ComputedRef<Theme>;

useLocale()

获取当前语言。

typescript

function useLocale(): ComputedRef<SupportedLocale>;

useGlobalSize()

获取全局尺寸。

typescript

function useGlobalSize(): ComputedRef<ComponentSize>;

useComponentSize(componentSize?)

获取组件尺寸（支持组件级别覆盖）。

typescript

function useComponentSize(
  componentSize?: Ref<ComponentSize | undefined> | ComponentSize
): ComputedRef<ComponentSize>;

useNeonEffect()

获取霓虹效果开关。

typescript

function useNeonEffect(): ComputedRef<boolean>;

useAnimation()

获取动画开关。

typescript

function useAnimation(): ComputedRef<boolean>;

useNamespace(block?)

获取命名空间工具（BEM 规范）。

typescript

function useNamespace(block?: string): {
  namespace: ComputedRef<string>;
  b: ComputedRef<string>;
  e: (element: string) => ComputedRef<string>;
  m: (modifier: string) => ComputedRef<string>;
  em: (element: string, modifier: string) => ComputedRef<string>;
  is: (name: string, state?: boolean | Ref<boolean>) => ComputedRef<string>;
};

useZIndex(offset?)

获取 z-index 值。

typescript

function useZIndex(offset?: number): ComputedRef<number>;

最佳实践

1. 应用级配置

在应用的根组件使用 ConfigProvider：

vue

<!-- App.vue -->
<template>
  <ExConfigProvider theme="neon-blue" locale="zh-CN" :neon-effect="true" :animation="true">
    <RouterView />
  </ExConfigProvider>
</template>

2. 局部配置覆盖

在特定区域使用不同配置：

vue

<template>
  <ExConfigProvider theme="neon-blue">
    <!-- 大部分内容使用霓虹蓝主题 -->
    <div class="main-content">
      <ExButton type="primary">主要按钮</ExButton>
    </div>

    <!-- 特定区域使用霓虹粉主题 -->
    <ExConfigProvider theme="neon-pink">
      <div class="special-section">
        <ExButton type="primary">特殊按钮</ExButton>
      </div>
    </ExConfigProvider>
  </ExConfigProvider>
</template>

3. 响应式主题切换

vue

<script setup>
import { ref, watch } from 'vue';

const theme = ref('neon-blue');

// 保存主题到 localStorage
watch(theme, newTheme => {
  localStorage.setItem('theme', newTheme);
});

// 从 localStorage 恢复主题
const savedTheme = localStorage.getItem('theme');
if (savedTheme) {
  theme.value = savedTheme;
}
</script>

<template>
  <ExConfigProvider :theme="theme">
    <div class="theme-switcher">
      <ExButton @click="theme = 'neon-blue'">霓虹蓝</ExButton>
      <ExButton @click="theme = 'neon-pink'">霓虹粉</ExButton>
      <ExButton @click="theme = 'dark'">暗黑</ExButton>
    </div>

    <RouterView />
  </ExConfigProvider>
</template>

4. 无障碍支持

ConfigProvider 会自动处理无障碍相关的配置：

尊重用户的 prefers-reduced-motion 设置
尊重用户的 prefers-color-scheme 设置
尊重用户的 prefers-contrast 设置

vue

<template>
  <ExConfigProvider
    :animation="!prefersReducedMotion"
    :theme="prefersDarkMode ? 'dark' : 'neon-blue'"
  >
    <App />
  </ExConfigProvider>
</template>

主题定制

ConfigProvider 支持通过 CSS 变量进行主题定制：

css

/* 自定义霓虹蓝主题 */
[data-theme='neon-blue'] {
  --ex-color-primary: #00f0ff;
  --ex-color-secondary: #ff007f;
  --ex-color-bg-primary: #0a0a0a;
}

/* 自定义霓虹粉主题 */
[data-theme='neon-pink'] {
  --ex-color-primary: #ff007f;
  --ex-color-secondary: #00f0ff;
  --ex-color-bg-primary: #0a0a0a;
}

ConfigProvider 全局配置 ​

基础用法 ​

国际化（i18n） ​

一、快速开始（推荐） ​

二、手动集成 vue-i18n ​

组件中使用 ​

主题切换 ​

当前主题：neon-blue

语言切换 ​

全局尺寸 ​

霓虹效果控制 ​

霓虹卡片

动画控制 ​

悬停卡片

自定义命名空间 ​

自定义 z-index ​

综合演示 ​

🎛️ 配置控制面板

📱 效果预览

嵌套使用 ​

实际应用场景 ​

🎮 游戏大厅

快速操作

组合式 API ​

useNamespace 示例 ​

API ​

ConfigProvider Props ​

ConfigProvider Slots ​

Composables ​

useConfig() ​

useTheme() ​

useLocale() ​

useGlobalSize() ​

useComponentSize(componentSize?) ​

useNeonEffect() ​

useAnimation() ​

useNamespace(block?) ​

useZIndex(offset?) ​

最佳实践 ​

1. 应用级配置 ​

2. 局部配置覆盖 ​

3. 响应式主题切换 ​

4. 无障碍支持 ​

主题定制 ​

ConfigProvider 全局配置

基础用法

国际化（i18n）

一、快速开始（推荐）

二、手动集成 vue-i18n

组件中使用

主题切换

语言切换

全局尺寸

霓虹效果控制

动画控制

自定义命名空间

自定义 z-index

综合演示

嵌套使用

实际应用场景

组合式 API

useNamespace 示例

API

ConfigProvider Props

ConfigProvider Slots

Composables

useConfig()

useTheme()

useLocale()

useGlobalSize()

useComponentSize(componentSize?)

useNeonEffect()

useAnimation()

useNamespace(block?)

useZIndex(offset?)

最佳实践

1. 应用级配置

2. 局部配置覆盖

3. 响应式主题切换

4. 无障碍支持

主题定制