X-Next

Appearance

ConfigProvider 全局配置 ​

为子树内的组件提供统一的全局配置：尺寸、主题色与语言。

何时使用 ​

  • 需要统一调整一批组件的默认尺寸，而不想逐个传 size
  • 需要运行时切换品牌主题色
  • 需要切换组件内置文案的语言
  • 需要统一替换空态展示内容

基础用法 ​

包裹需要生效的区域即可，默认渲染一个 div 作为配置边界。

vue
<template>
  <x-config-provider size="small">
    <x-input placeholder="输入框" />
    <x-button type="primary">按钮</x-button>
  </x-config-provider>
</template>

尺寸继承 ​

size 的优先级为：组件自身 props > 父级（如 FormItem）> ConfigProvider > 组件默认值。

切换下面的尺寸，观察内部组件统一变化：

组件显式指定的尺寸不受全局配置影响：

vue
<template>
  <!-- 内部按钮与输入框统一使用 small -->
  <x-config-provider size="small">
    <x-button>继承全局</x-button>
    <!-- 显式指定优先于全局配置 -->
    <x-button size="large">显式 large</x-button>
  </x-config-provider>
</template>

Table 的默认尺寸为 large，未配置全局尺寸时保持该默认值：

名称
继承 small
vue
<template>
  <x-config-provider size="small">
    <x-table :columns="columns" :data="data" :pagination="false" />
  </x-config-provider>
</template>

主题色 ​

传入 themeColor 会派生整条色阶（基色 + 9 档）并写入配置边界元素，因此可以只对局部区域换色，不影响页面其余部分。

vue
<template>
  <!-- 只影响这个边界内的组件 -->
  <x-config-provider theme-color="#0f766e">
    <x-button type="primary">主色按钮</x-button>
    <x-switch :model-value="true" />
  </x-config-provider>
</template>

需要暗色色阶时传 dark：

vue
<template>
  <x-config-provider theme-color="#1c61ff" dark>
    <x-button type="primary">暗色色阶</x-button>
  </x-config-provider>
</template>

语言 ​

传入 locale 切换组件内置文案。语言包从 x-next 导入：

暂无数据
vue
<template>
  <x-config-provider :locale="locale">
    <x-empty />
    <x-pagination :total="128" />
  </x-config-provider>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { zhCN, enUS } from 'x-next';

const locale = ref(zhCN);
// 切换为英文
// locale.value = enUS;
</script>

空态插槽 ​

empty 插槽会接管子树内组件的空态渲染，回调参数 component 标明请求来源，便于按组件区分样式。

名称
自定义空态来源：table
vue
<template>
  <x-config-provider>
    <!-- component 标明来源：empty / select / table / dropdown -->
    <template #empty="{ component }">
      <div>暂无内容（来源：{{ component }}）</div>
    </template>
    <x-select :options="[]" style="width: 200px" />
    <x-table :columns="columns" :data="[]" :pagination="false" />
  </x-config-provider>
</template>

<script setup lang="ts">
const columns = [{ title: '名称', dataIndex: 'name' }];
</script>

不产生额外 DOM ​

默认会渲染一个包裹元素作为配置边界。若不想引入额外节点（例如在表格单元格内），可传 tag={null}：

vue
<template>
  <!-- 不产生包裹元素，仅向子树注入配置 -->
  <x-config-provider :tag="null" size="small">
    <x-button>按钮</x-button>
  </x-config-provider>
</template>

注意：tag={null} 时没有可承载 CSS 变量的元素，themeColor 不会生效，需要另行指定承载元素。

按需导入 ​

ts
import { ConfigProvider } from 'x-next';

ConfigProvider 自身没有样式，无需单独引入样式文件；它包裹的组件按各自方式引入（base.css 为共享基础层，多个组件只需引入一次）：

ts
import 'x-next/style/base.css';
import 'x-next/style/button.css';

ConfigProvider Props ​

参数说明类型默认值
size全局组件尺寸'mini' | 'small' | 'medium' | 'large'-
locale语言包Locale全局默认（zh-CN）
themeColor主题色种子，派生整条色阶并写入边界元素string-
dark是否使用暗色色阶booleanfalse
tag包裹元素标签；传 null 不产生额外 DOMstring | null'div'

ConfigProvider Slots ​

插槽名说明参数
default配置生效的内容-
empty子树内组件的空态内容{ component }

已知限制 ​

  • themeColor 只派生 primary 色阶。success / warning / danger / strong 等状态色不受影响，需要改种子色请用构建期方式（见「样式与主题」）。
  • 不支持 prefixCls 自定义类名前缀，组件类名固定使用 x 前缀。
  • 语言包当前覆盖分页、表格、弹窗、空态、网络状态、图片预览、表单校验提示、日期 / 时间选择器，以及 Tabs、Dropdown、Menu、Message、Notification、Spin、Tag、InputPassword 等组件内置文案。