Semi Design ConfigProvider 全局配置与 semiGlobal 默认 Props 覆盖实战指南
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、多语言与组件默认行为的统一治理。