Semi Design ConfigProvider 全局配置与 semiGlobal 默认 Props 覆盖实战指南

原创2026-09-23 10:29:201,713 阅读
文章标签:前端UI组件设计系统

Semi Design ConfigProvider 全局配置与 semiGlobal 默认 Props 覆盖实战指南

ConfigProvider 是 Semi Design 提供的全局配置入口,基于 React Context 机制为组件树统一注入 timeZone、direction、locale、getPopupContainer 等跨组件公有配置;当 ConfigProvider 暴露的参数仍不满足需求时,semiGlobal.config.overrideDefaultProps 可在全局范围内直接改写任意组件的默认 Props。本文将结合 @douyinfe/semi-ui 源码,系统讲解两种覆盖方式的选型、完整配置示例、响应式断点订阅、RTL 适配与时区标识规则,帮助你在一套代码中低成本实现"多时区、多语言、RTL、定制默认行为"的规模化组件配置。

使用场景:两种全局覆盖配置如何选型

Semi Design 将"覆盖配置"划分为两类场景,对应两套不同的 API:

场景 手段 影响范围
需要覆盖多个组件公有 Props(如 timeZone、rtl) ConfigProvider React 节点树中的子组件
ConfigProvider 暴露参数不满足,需要修改某个组件的某类 Props(如让所有 Button 的 theme 为 solid,或所有 Popover 的 zIndex 为固定值) semiGlobal 整个站点(单例,全局生效)

两者的根本区别在于作用机制:ConfigProvider 借助 React Context 向下传递,作用域是声明它的组件子树;semiGlobal 则是一个全局单例对象,作用于所有组件实例的默认 Props。下文分别展开。

ConfigProvider 的实现机制:基于 React Context

ConfigProvider 的底层实现位于 packages/semi-ui/configProvider/index.tsx:

  • 通过 React.createContext<ContextValue>({}) 创建上下文,上下文值的完整结构定义在 packages/semi-ui/configProvider/context.tsx,包含 direction、timeZone、locale、getPopupContainer、responsiveMap、onBreakpoint、screens 等字段;
  • 渲染时用 <Context.Provider value={...}> 包裹子组件,因此只有 ConfigProvider 之下的子组件能感知到配置;
  • 当 direction === 'rtl' 时,渲染逻辑会额外包一层 div.semi-rtl(renderChildren 方法),这是 RTL 生效的样式载体;
  • ConfigConsumer 就是 Context.Consumer 的别名导出(见源码 export const ConfigConsumer = Context.Consumer),供函数组件或非组件场景手动消费上下文。

正因为依赖 Context 机制,ConfigProvider 天然支持嵌套与局部作用域:你可以在应用根部放一个全局 ConfigProvider,再在某个局部区域嵌套一个覆盖了不同 locale 或 direction 的 ConfigProvider。

基本用法:为时间类组件全局配置时区

如何引入

import { ConfigProvider } from '@douyinfe/semi-ui';

时区基本用法

通过传入 timeZone 参数,可以为 DatePicker、TimePicker 等时间类组件统一配置时区。下面的示例构建了一个从 GMT-11:00 到 GMT+14:00 的时区选择器,切换时区后下方的时间组件会同步按所选时区展示时间:

import React, { useMemo, useState } from 'react';
import { ConfigProvider, Select, DatePicker, TimePicker } from '@douyinfe/semi-ui';

function Demo(props = {}) {
    const [timeZone, setTimeZone] = useState('GMT+08:00');
    const defaultTimestamp = 1581599305265;
    const gmtList = useMemo(() => {
        const list = [];
        for (let hourOffset = -11; hourOffset <= 14 ; hourOffset++) {
            const prefix = hourOffset >= 0 ? '+' : '-';
            const hOffset = Math.abs(parseInt(hourOffset, 10));
            list.push(`GMT${prefix}${String(hOffset).padStart(2, '0')}:00`);
        }
        return list;
    }, []);

    return (
        <ConfigProvider timeZone={timeZone}>
            <div style={{ width: 300 }}>
                <h5 style={{ margin: 10 }}>Select Time Zone:</h5>
                <Select
                    placeholder={'请选择时区'}
                    style={{ width: 300 }}
                    value={timeZone}
                    showClear={true}
                    onSelect={value => setTimeZone(value)}
                >
                    {gmtList.map(gmt => (
                        <Select.Option key={gmt} value={gmt}>
                            {gmt}
                        </Select.Option>
                    ))}
                </Select>
                <br/>
                <br/>
                <DatePicker type={'dateTime'} defaultValue={defaultTimestamp} onChange={(date, dateString) => console.log('DatePicker changed: ', date, dateString)} />
                <br/>
                <br/>
                <TimePicker defaultValue={defaultTimestamp} onChange={(date, dateString) => console.log('DatePicker changed: ', date, dateString)} />
            </div>
        </ConfigProvider>
    );
}

从源码看,timeZone 真正被消费的位置在 packages/semi-foundation/datePicker/foundation.ts:initFromProps 会调用 parseWithTimezone 将本地时间按 timeZone 转换为目标时区展示,回传时再通过 zonedTimeToUtc 转回 UTC(相关逻辑也见 packages/semi-foundation/timePicker/foundation.ts)。仓库内的测试用例(如 packages/semi-ui/datePicker/test/datePicker.test.js 中 check inputValue is correct when change timeZone)验证了切换时区后输入值与受控值的正确性。

手动获取配置值:ConfigConsumer

通常情况下,组件内部会自动消费 ConfigProvider 的值,无需关心。但某些特殊场景(如自定义组件需要读取时区、方向做额外逻辑),你可以通过 ConfigConsumer 手动获取:

import React, { useMemo, useState } from 'react';
import { ConfigProvider, ConfigConsumer, Select, DatePicker, TimePicker, Typography } from '@douyinfe/semi-ui';

function Demo(props = {}) {
  const [timeZone, setTimeZone] = useState('GMT+08:00');
  const defaultTimestamp = 1581599305265;
  const gmtList = useMemo(() => {
    const list = [];
    for (let hourOffset = -11; hourOffset <= 14; hourOffset++) {
      const prefix = hourOffset >= 0 ? '+' : '-';
      const hOffset = Math.abs(parseInt(hourOffset, 10));
      list.push(`GMT${prefix}${String(hOffset).padStart(2, '0')}:00`);
    }
    return list;
  }, []);

  return (
    <ConfigProvider timeZone={timeZone}>
      {/*...*/}
      <ConfigConsumer>
        {(value) => {
          return <Typography.Text ellipsis={{ showTooltip: {opts:{style:{minWidth:"1200px"}} }}}  style={{ width: 600 }}>
            {JSON.stringify(value)}
          </Typography.Text>
       }}
      </ConfigConsumer>
      {/*...*/}
    </ConfigProvider>
  );
}

这里 value 即为 Context 中传递的完整配置对象,你可以按需取用其中的 timeZone、direction、locale、getPopupContainer、responsiveMap 等字段。

响应式断点监听

ConfigProvider 支持配置响应式断点,并在断点变化时进行订阅回调(该能力在 >=2.97.0 版本提供)。

开启监听与自定义断点

  • 通过 responsiveObserve 开启断点监听(建议只在确实需要订阅的场景开启);
  • 通过 responsiveMap 自定义断点(未传入时使用默认断点,可通过 ConfigProvider.defaultResponsiveMap 获取)。
import React, { useEffect, useState } from 'react';
import { ConfigProvider, ConfigConsumer, Typography } from '@douyinfe/semi-ui';

function BreakpointSubscriber({ onBreakpoint, screens }) {
    const [subscribedScreens, setSubscribedScreens] = useState(screens);

    useEffect(() => {
        if (!onBreakpoint) {
            return;
        }
        const unsubscribe = onBreakpoint(next => {
            setSubscribedScreens(next);
        });
        return unsubscribe;
    }, [onBreakpoint]);

    return (
        <Typography.Text>
            {JSON.stringify(subscribedScreens || screens)}
        </Typography.Text>
    );
}

function Demo() {
    return (
        <ConfigProvider
            responsiveObserve
            responsiveMap={{
                xs: '(max-width: 575px)',
                sm: '(min-width: 576px)',
                md: '(min-width: 768px)',
                lg: '(min-width: 992px)',
                xl: '(min-width: 1200px)',
                xxl: '(min-width: 1600px)',
            }}
        >
            <ConfigConsumer>
                {({ onBreakpoint, screens }) => (
                    <BreakpointSubscriber onBreakpoint={onBreakpoint} screens={screens} />
                )}
            </ConfigConsumer>
        </ConfigProvider>
    );
}

订阅 API 的两种签名

onBreakpoint 支持两种签名,均会返回取消订阅函数:

  • onBreakpoint((screens) => void):回调拿到完整的 screens 映射({ xs, sm, md, lg, xl, xxl } 的布尔值对象);
  • onBreakpoint(['md', 'lg'], (screen, match) => void):只监听指定断点,回调拿到单个断点的变化。

订阅时回调会立即执行一次,传入的就是当前各断点的命中情况,因此你不需要在初始挂载时再单独调用一次 window.matchMedia。

注意事项与实现细节

  • 由于性能考虑,responsiveObserve 默认值为 false,不开启时不会注册任何 matchMedia 监听;
  • onBreakpoint / screens 不属于 ConfigProvider 的 props,需要通过 ConfigConsumer 获取;
  • responsiveMap 是引用比较:如果直接 inline 写对象(每次 render 引用都不同),会被识别为发生变化并重新注册全部监听。建议把它定义在组件外,或使用 useMemo 保证引用稳定。

从源码 packages/semi-ui/configProvider/index.tsx 可以看到其实现策略:

  • 断点类型 Breakpoint('xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl')与 BreakpointScreens 结构定义在 packages/semi-ui/configProvider/responsiveTypes.ts;
  • 默认断点映射 defaultResponsiveMap 即上文示例中的六组 media query,同时作为静态属性 ConfigProvider.defaultResponsiveMap 暴露;
  • 开启后采用懒注册:首次出现订阅者时才通过 registerMediaQueries 注册 window.matchMedia 监听(底层工具为 packages/semi-ui/_utils/index.tsx 中的 registerMediaQuery,内部优先使用 addEventListener,旧环境回退到 addListener);当最后一个订阅者取消订阅后会自动注销监听以节省资源(componentDidUpdate 中关闭 responsiveObserve 也会触发注销);
  • 注册前会先同步读取一次各断点的 matches 写入 currentScreensRef 与 state.screens,保证订阅回调立即执行时拿到的是最新快照而不是过期的异步 state。

RTL/LTR 全局文本方向

全局配置 direction 可以改变组件的文本方向(自 1.8.0 版本支持):

  • rtl 表示从右到左(类似希伯来语或阿拉伯语);
  • ltr 表示从左到右(类似中文、英语等大部分语言)。
import React, { useState } from 'react';
import { ConfigProvider, ButtonGroup, Button } from '@douyinfe/semi-ui';

function Demo(props = {}) {
    const [direction, setDirection] = useState();
    return (
        <div>
            <div style={{ marginBottom: 20 }}>
                <ButtonGroup>
                    <Button onClick={() => setDirection('ltr')}>LTR</Button>
                    <Button onClick={() => setDirection('rtl')}>RTL</Button>
                </ButtonGroup>
            </div>
            <ConfigProvider direction={direction}>
                {/* 此处放置你的业务组件,如 Button、Input、Select、DatePicker、Timeline、Steps、Breadcrumb、Nav、Pagination 等 */}
            </ConfigProvider>
        </div>
    );
}

原文档中的完整演示(content/other/configprovider/index.md 的 RTL/LTR 小节)覆盖了 Button、Input、TextArea、Switch、Checkbox、Radio、DatePicker、TimePicker、Select、Cascader、Breadcrumb、Nav、Pagination、Steps、Badge、Avatar、Tag、Popover、Tooltip、Rating、Timeline、Notification、Modal、Toast、Spin 等大量组件,可直接照搬运行观察 RTL 效果。使用 RTL 时需注意以下几点:

  • Modal、Notification、Toast 的命令式调用需要通过 prop 传 direction(这些组件由命令式 API 挂载,不在 ConfigProvider 的 React 节点树内,见 packages/semi-ui/notification/index.tsx、packages/semi-ui/toast/index.tsx 中对 direction 的处理);
  • 如果你想对有方向性的 Icon 做 RTL 国际化,需要自己单独处理。Semi 认为对 Icon 做 RTL 会使其难以理解和维护,其他组件内的 icon Semi 已经做了 RTL 适配;
  • Table 的树形数据暂不支持 RTL(Chrome、Safari 浏览器表现与 Firefox 表现不同),固定列在 v2.32 版本开始支持 RTL。

从源码看,RTL 的实现是通过 renderChildren 在 direction === 'rtl' 时额外包裹 <div className="semi-rtl">,组件层的样式通过 semi-rtl 前缀的 CSS 规则实现镜像布局。

API 参考

ConfigProvider 的完整 Props 如下(与其在 packages/semi-ui/configProvider/index.tsx 中声明的 ConfigProviderProps 一致):

属性 说明 类型 默认值
direction 设置文本的方向 ltr | rtl ltr
responsiveObserve 是否开启响应式断点监听。默认关闭以避免全局注册 matchMedia 带来的性能开销;开启后在首次订阅时懒注册监听,无订阅时会自动注销,>=2.97.0 boolean false
responsiveMap 自定义断点配置,key 为 xs/sm/md/lg/xl/xxl,value 为 media query 字符串;未传入时使用默认断点(可通过 ConfigProvider.defaultResponsiveMap 获取),>=2.97.0 object 默认断点映射
getPopupContainer 指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relative。这会改变浮层 DOM 树位置,但不会改变视图渲染位置 function(): HTMLElement () => document.body
locale 多语言配置,同 LocaleProvider 中 locale 参数的用法(如果同时在 ConfigProvider 和 LocaleProvider 中配置 locale,前者优先级高于后者) object 简体中文默认文案
timeZone 时区标识,支持数字偏移与 IANA 标识,详见下文"时区标识详解" string | number —

时区标识详解

timeZone 支持两种形式的取值:

  • 数字,例如 1、-9.5,代表距离 UTC 的时间偏移,单位为小时,可以为负数或小数;
  • 字符串:可以是 GMT-09:30、GMT+08:00 这类以 "GMT" 开头的偏移字符串,也可以是 IANA 标识,如 Asia/Shanghai、America/Los_Angeles 等。

当你使用数字或 GMT-09:00 类似写法时,Semi 内部会将这些时区标识转换为 IANA 标识:

  • 例如设置 -9 或 GMT-09:00 时,会转换成 Pacific/Gambier。某些数字对应的 IANA 标识可能有多个,Semi 首选无夏令时的 IANA 标识;
  • 如果该数字没有对应的无夏令时 IANA 标识,如 -3.5、3.5、10.5、13.75,这时映射的就是一个有夏令时的 IANA 标识,有夏令时的时区会在偏移量上进行调整(如 -3.5 会在进入夏令时后在标准时间上增加 1 小时)。

如果你想准确设置一个地区的时区,推荐直接使用 IANA 标识而不是偏移量写法,可以避免夏令时带来的偏差。

该转换逻辑在源码中有清晰体现: packages/semi-foundation/utils/date-fns-extra.ts 中定义了 IANAOffsetMap(数字偏移到 IANA 标识的映射表,如 -9 → Pacific/Gambier、8 → Asia/Shanghai 等)、IANAEtcGMTOffsetMap(Etc/GMT* 无夏令时标识),以及核心函数 toIANA(tz);utcToZonedTime 与 zonedTimeToUtc 在调用 date-fns-tz 之前都会先经过 toIANA 归一化。这也解释了为什么偏移量写法会优先落到无夏令时的标识:映射表按此规则编排,只有像 -3.5、10.5、13.75 这类没有无夏令时替代项的偏移,才会映射到带夏令时的时区。

FAQ:ConfigProvider 未提供全局 prefixCls 怎么办

ConfigProvider 中没有提供全局自定义 prefix classname 的功能。如果确实有类似需求(例如 SDK 中使用了 Semi,期望打包的 DOM 样式不带 .semi-xx 前缀,以免被宿主的全局 CSS 影响),实现方式如下:

由于 prefixCls 需要同时被组件层的 JS/CSS 消费,Semi 将此开关放在了 webpack plugin 的配置项中,而不是作为 ConfigProvider 的配置项。如果你使用 webpack,请在 SemiWebpackPlugin 的参数中进行配置:

// webpack配置示例
const SemiWebpackPlugin = require('@douyinfe/semi-webpack-plugin').default;
module.exports = {
+    plugins: [new SemiWebpackPlugin({ prefixCls: 'imes' })],
}

对应插件实现在 packages/semi-webpack/src 中,通过编译期改写类名前缀,保证 JS 层与 SCSS 层同步生效。

semiGlobal:全局覆盖组件默认 Props

除了 ConfigProvider 外,你还可以通过 semiGlobal 配置覆盖全局组件的默认 Props。该能力在 v2.59.0 之后提供。

用法

在 semiGlobal.config.overrideDefaultProps 中配置组件默认 Props。你需要将配置放到整个站点的入口处,即优先于所有 Semi 组件执行:

import { semiGlobal } from '@douyinfe/semi-ui';

semiGlobal.config.overrideDefaultProps = {
    Select: {
        zIndex: 2000,
    },
    Tooltip: {
        zIndex: 2001,
        trigger: 'click'
    },
};

例如上面的配置会将所有 Button 默认设置为 warning(原文示例指向 Button,配置键以实际组件名为准)、所有 Select 的 zIndex 默认设为 2000、所有 Tooltip 的 zIndex 设为 2001 且默认触发方式改为 click。

注意事项:semiGlobal 是单例模式,会影响整个站点。如果你只想覆盖某些地方的某些组件 Props,建议不要使用 semiGlobal,而是将对应需要覆盖的组件封装一层,并在封装组件里传入修改后的默认 props。

实现原理

从源码结构看,semiGlobal 的定义在 packages/semi-ui/_utils/semi-global.ts:

  • 它是一个 class SemiGlobal 的单例实例(export default new SemiGlobal()),内部维护 config 对象;
  • overrideDefaultProps 的类型定义覆盖了 AutoComplete、Avatar、Button、Cascader、Checkbox、DatePicker、Dropdown、Form、Input、Modal、Navigation、Notification、Popconfirm、Popover、Progress、Radio、Select、SideSheet、Slider、Spin、Switch、Table、Tabs、Tag、TimePicker、Toast、Tooltip、Tree、TreeSelect、Typography、Upload 等几十个组件的 Partial<Props> 类型(从 semi-global.ts 的 SemiGlobalConfig 接口可见完整清单)。

各组件消费该配置的统一入口是 packages/semi-ui/_utils/index.tsx 中的 getDefaultPropsFromGlobalConfig(componentName, semiDefaultProps):

  • 它基于 Proxy 包装组件的默认 Props:读取某个 key 时,若全局配置中存在该 key 则优先返回全局值,否则回退到组件自身默认值;
  • ownKeys 会将全局配置的 key 合并进默认 Props 的枚举,保证 Object.keys(defaultProps) 等场景也能感知到覆盖项;
  • 组件侧通过 static defaultProps = getDefaultPropsFromGlobalConfig(Button.__SemiComponentName__) 接入(可见于 packages/semi-ui/button/index.tsx 等多个组件),因此配置在入口执行一次后,全站所有组件实例的默认值都会被改写。

仓库内还提供了针对该能力的测试用例 packages/semi-ui/_utils/test/overrideDefaultProps.test.js,覆盖了 Input.showClear、Checkbox.defaultChecked、冻结对象(Object.freeze)等场景,验证了覆盖优先级与 Proxy 不变式处理。

小结

ConfigProvider 与 semiGlobal 构成了 Semi Design 两层互补的全局配置体系:

  • 需要树形作用域的跨组件公有配置(时区、方向、语言、弹层挂载点、响应式断点),用 ConfigProvider + ConfigConsumer;
  • 需要站点级全局改写某个组件默认 Props(zIndex、trigger、theme 等),用 semiGlobal.config.overrideDefaultProps;
  • 想要替换类名前缀以隔离宿主样式,则走 SemiWebpackPlugin 的 prefixCls 配置。

三者各司其职,配合使用即可在不动业务代码的前提下,完成多时区、RTL、多语言与组件默认行为的统一治理。

登录后查看全文
semi-design