--- localeCode: zh-CN order: 95 category: 其他 title: ConfigProvider 全局配置 icon: doc-configprovider dir: column brief: 为组件提供统一的全局化配置。 --- ## 使用场景 覆盖配置分为两种场景 - 需要覆盖多个组件公有 Props 配置（例如 `timezone`、`rtl`），使用 `ConfigProvider` - 当 `ConfigProvider` 暴露参数未能满足，希望修改全局修改某个组件的 某类 Props（例如期望将所有`Button`的 `theme` 都配置为 `solid` 或所有 `Popover`的 `zIndex`），使用 `semiGlobal` ## ConfigProvider ConfigProvider 借助 React Context 机制实现，因此它能影响 React 节点树中的子组件 ## 代码演示 ### 如何引入 ```jsx import import { ConfigProvider } from '@douyinfe/semi-ui'; ``` ### 基本用法 通过传入 timeZone 参数，用户可以为时间类组件配置时区： ```jsx live=true dir="column" hideInDSM 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 (
Select Time Zone:


console.log('DatePicker changed: ', date, dateString)} />

console.log('DatePicker changed: ', date, dateString)} />
); } ``` ### 手动获取值 通常情况下，组件内部会自动获取 ConfigProvider 的值自动消费，无需关心。但是一些特殊场景，你可能需要手动获取值来进行其他操作。 使用 ConfigConsumer 获取 ConfigProvider 的值 ```jsx live=true dir="column" hideInDSM 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 ( {/*...*/} {(value) => { return {JSON.stringify(value)} }} {/*...*/} ); } ``` ### 响应式断点监听 ConfigProvider 支持配置响应式断点，并在断点变化时进行订阅回调。 - 由于性能考虑，`responsiveObserve` 默认值为 `false`，不开启时不会注册任何 `matchMedia` 监听。 - `onBreakpoint` / `screens` 不属于 ConfigProvider 的 props，需要通过 `ConfigConsumer` 获取。 - 订阅时回调会**立即执行一次**，传入的就是当前各断点的命中情况，因此你不需要在初始挂载时再单独调用一次 `window.matchMedia`。 - `responsiveMap` 是引用比较：如果直接 inline 写对象（每次 render 引用都不同），会被识别为发生变化并重新注册全部监听。建议把它定义在组件外，或使用 `useMemo` 保证引用稳定。 #### 开启监听与自定义断点 - 通过 `responsiveObserve` 开启断点监听（建议只在确实需要订阅的场景开启） - 通过 `responsiveMap` 自定义断点（未传入时使用默认断点） ```jsx 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 ( {JSON.stringify(subscribedScreens || screens)} ); } function Demo() { return ( {({ onBreakpoint, screens }) => ( )} ); } ``` #### 订阅 API `onBreakpoint` 支持两种签名，均会返回取消订阅函数： - `onBreakpoint((screens) => void)`：回调拿到完整的 screens 映射 - `onBreakpoint(['md', 'lg'], (screen, match) => void)`：只监听指定断点，回调拿到单个断点变化 ### RTL/LTR 全局配置 `direction` 可以改变组件的文本方向（1.8.0）。 `rtl` 表示从右到左 (类似希伯来语或阿拉伯语)， `ltr` 表示从左到右 (类似中文、英语等大部分语言)。 特殊组件： - Modal，Notification，Toast 的命令式调用需要通过 prop 传 `direction`。 - 如果你想对有方向性的 Icon 做 RTL 国际化，需要自己单独进行处理。我们认为对 Icon 进行 RTL 会让它变得难以理解和维护。其他组件内的 icon Semi 已经做了 RTL 适配。 - Table 的树形数据暂不支持 RTL（[Chrome、Safari 浏览器表现与 Firefox 表现不同](https://codesandbox.io/s/table-rtl-treedata-uy7gzl?file=/src/App.jsx)），固定列在 v2.32 版本支持 RTL。 ```jsx live=true dir="column" hideInDSM import React, { useState } from 'react'; import { ConfigProvider, ButtonGroup, Button, Row, Col, Notification, DatePicker, TimePicker, Timeline, Popover, Tag, Tooltip, Badge, Avatar, Steps, Pagination, Modal, Breadcrumb, Rating, Nav, Spin, Cascader, Radio, Select, Input, Typography, TextArea, Checkbox, Switch } from '@douyinfe/semi-ui'; import { IconVigoLogo, IconEdit, IconCamera, IconList, IconSidebar, IconChevronDown } from '@douyinfe/semi-icons'; function Demo(props = {}) { const { Option } = Select; const [direction, setDirection] = useState(); const flexStyle = { display: 'flex', marginBottom: 32, flexWrap: 'wrap' }; const titleStyle = { margin: '50px 0 16px 0' }; const rowStyle = { margin: '16px 10px' }; const badgeStyle = { width: '42px', height: '42px', borderRadius: '4px', display: 'inline-block', }; const tagStyle = { marginRight: 8, marginBottom: 8 }; const buttonStyle = { ...tagStyle }; const opts = { title: 'Hi,Bytedance', content: 'ies dance dance dance', duration: 3, direction, }; const treeData = [ { label: '浙江省', value: 'zhejiang', children: [ { label: '杭州市', value: 'hangzhou', children: [ { label: '西湖区', value: 'xihu', }, { label: '萧山区', value: 'xiaoshan', }, { label: '临安区', value: 'linan', }, ], }, { label: '宁波市', value: 'ningbo', children: [ { label: '海曙区', value: 'haishu', }, { label: '江北区', value: 'jiangbei', } ] }, ], } ]; return (

Buttons

Input





Suffix} showClear>