ConfigProvider 全局化配置

为组件提供统一的语言、主题、尺寸等全局配置

何时使用

  • 需要全局配置语言、主题时。

导入

import { ConfigProvider } from "@reglow/reui";
import { useConfigProvider, useComponentConfig, useComponentSize } from "@reglow/reui";

基础用法

在根组件包裹 ConfigProvider，所有子组件均可通过 useConfigProvider() 获取配置。

<script setup lang="ts">
import { ConfigProvider } from "@reglow/reui";
</script>

<template>
  <ConfigProvider locale="zh-CN" component-size="default">
    <App />
  </ConfigProvider>
</template>

更多示例

主题模式

通过 theme.mode 控制明暗模式，会自动切换 document.documentElement 的 dark class。

<script setup lang="ts">
import { ref, computed } from "vue";

const mode = ref<"light" | "dark">("dark");
const theme = computed(() => ({ mode: mode.value }));
</script>

<template>
  <ConfigProvider :theme="theme">
    <App />
  </ConfigProvider>
</template>

弹层容器

通过 getPopupContainer 统一定义弹层（Popover、Select、Dropdown 等）的挂载容器。

<script setup lang="ts">
import { ConfigProvider } from "@reglow/reui";

// 所有弹层挂载到 body
const getPopupContainer = () => document.body;
</script>

<template>
  <ConfigProvider :get-popup-container="getPopupContainer">
    <App />
  </ConfigProvider>
</template>

组件级配置

通过 componentConfig 为特定组件设置默认属性。

<script setup lang="ts">
import { ConfigProvider } from "@reglow/reui";

const componentConfig = {
  Button: { type: "primary" },
  Table: { bordered: true },
  Modal: { maskClosable: false },
};
</script>

<template>
  <ConfigProvider :component-config="componentConfig">
    <App />
  </ConfigProvider>
</template>

嵌套配置

ConfigProvider 支持嵌套，内层配置会覆盖外层对应字段。

<template>
  <ConfigProvider locale="zh-CN" component-size="default">
    <MainLayout />

    <!-- 这个区域使用英文 + 小尺寸 -->
    <ConfigProvider locale="en-US" component-size="small">
      <EnglishPanel />
    </ConfigProvider>
  </ConfigProvider>
</template>

在子组件中消费配置

使用 useConfigProvider、useComponentConfig、useComponentSize 三个 composable 消费配置。

<script setup lang="ts">
import {
  useConfigProvider,
  useComponentConfig,
  useComponentSize,
} from "@reglow/reui";

// 获取完整配置
const { locale, direction, theme } = useConfigProvider();

// 获取特定组件配置
const tableConfig = useComponentConfig("Table");
// => { bordered: true }

// 获取生效尺寸（组件 prop 优先）
const props = defineProps<{ size?: "small" | "default" | "large" }>();
const size = useComponentSize(props.size);
</script>

完整配置示例

<script setup lang="ts">
import { ConfigProvider } from "@reglow/reui";

const getPopupContainer = (triggerNode?: HTMLElement) => {
  return triggerNode?.parentElement || document.body;
};
</script>

<template>
  <ConfigProvider
    locale="zh-CN"
    direction="ltr"
    component-size="default"
    :theme="{ mode: 'light', primaryColor: 'blue', radius: '0.5' }"
    namespace="re"
    :get-popup-container="getPopupContainer"
    :component-config="{
      Button: { type: 'primary' },
      Table: { bordered: true },
    }"
    :empty="{ description: '暂无数据' }"
    :pagination="{ pageSizeOptions: [10, 20, 50], showSizeChanger: true }"
    :form="{ requiredMark: true }"
  >
    <App />
  </ConfigProvider>
</template>

API

ConfigProvider Props

参数说明类型默认值
locale当前语言string'zh-CN'
direction文本方向'ltr' | 'rtl''ltr'
componentSize默认组件尺寸'small' | 'default' | 'large''default'
theme主题配置ThemeConfig{ mode: 'light' }
namespace类名前缀string're'
getPopupContainer弹层挂载容器函数(triggerNode?: HTMLElement) => HTMLElement-
componentConfig组件级默认配置Record<string, Record<string, any>>{}
empty空状态配置EmptyConfig-
pagination分页配置PaginationConfig-
form表单配置{ requiredMark: boolean }-
virtual是否开启虚拟滚动boolean-
class附加类名string-

ConfigProvider Slots

插槽名说明
default需要应用配置的子内容

ThemeConfig

参数说明类型默认值
mode主题模式'light' | 'dark''light'
primaryColor主色调string-
radius圆角string-

EmptyConfig

参数说明类型默认值
description空状态描述文案string-
image空状态图片string-

PaginationConfig

参数说明类型默认值
pageSizeOptions每页条数选项number[]-
showQuickJumper是否显示快速跳转boolean-
showSizeChanger是否显示条数选择器boolean-

Composable

useConfigProvider()

获取完整的 ConfigProvider 上下文，未包裹时返回安全默认值。

const {
  locale,           // ComputedRef<string>
  direction,        // ComputedRef<'ltr' | 'rtl'>
  componentSize,    // ComputedRef<'small' | 'default' | 'large'>
  theme,            // ComputedRef<ThemeConfig>
  namespace,        // ComputedRef<string>
  getPopupContainer,// ComputedRef<((triggerNode?) => HTMLElement) | undefined>
  componentConfig,  // ComputedRef<Record<string, Record<string, any>>>
  empty,            // ComputedRef<EmptyConfig | undefined>
  pagination,       // ComputedRef<PaginationConfig | undefined>
  form,             // ComputedRef<{ requiredMark: boolean } | undefined>
  virtual,          // ComputedRef<boolean | undefined>
} = useConfigProvider();

useComponentConfig(componentName)

获取特定组件的配置。

参数说明类型默认值
componentName组件名string-

返回 ComputedRef<Record<string, any>>，未配置时为 {}。

useComponentSize(propValue?)

获取生效的组件尺寸，优先级：组件 prop > ConfigProvider > 默认值。

参数说明类型默认值
propValue组件自身的 size prop'small' | 'default' | 'large'-

返回 ComputedRef<'small' | 'default' | 'large'>。

DOM 副作用

ConfigProvider 会在挂载时自动同步以下 DOM 属性：

属性说明
document.documentElement.dir同步 direction（ltr / rtl）
document.documentElement.lang同步 locale
document.documentElement.dark class同步 theme.mode（dark 时添加，light 时移除）

嵌套规则

  • ConfigProvider 可嵌套使用，内层通过 inject 获取最近的祖先配置。
  • 嵌套时内层配置覆盖外层同名属性。
  • 所有属性均为响应式，修改后子组件自动更新。
BackTop 回到顶部
页面内容较长时，滚动到指定高度后显示回到顶部按钮。
Cropper 图片裁切
自由裁切图片，支持缩放、旋转与固定比例