其他 · ConfigProvider
全局配置
为组件提供统一的全局化配置。

使用场景

覆盖配置分为两种场景
  • 需要覆盖多个组件公有 Props 配置(例如 timezonertl),使用 ConfigProvider
  • ConfigProvider 暴露参数未能满足,希望修改全局修改某个组件的 某类 Props(例如期望将所有Buttontheme 都配置为 solid 或所有 PopoverzIndex),使用 semiGlobal

ConfigProvider

ConfigProvider 借助 React Context 机制实现,因此它能影响 React 节点树中的子组件

代码演示

如何引入

基本用法

通过传入 timeZone 参数,用户可以为时间类组件配置时区:

手动获取值

通常情况下,组件内部会自动获取 ConfigProvider 的值自动消费,无需关心。但是一些特殊场景,你可能需要手动获取值来进行其他操作。
使用 ConfigConsumer 获取 ConfigProvider 的值

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 表现不同),固定列在 v2.32 版本支持 RTL,Slider 暂不支持 RTL。

API 参考

属性说明类型默认值
direction设置文本的方向ltr| rtlltr
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relative 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。function():HTMLElement() => document.body
locale多语言配置,同LocaleProviderlocale参数的用法(如果同时在ConfigProviderLocaleProvider中配置locale,前者优先级高于后者)object
timeZone时区标识string|number

时区标识

  • 数字,例如 1-9.5,代表距离 UTC 的时间偏移,单位为小时,可以为负数或小数;
  • 字符串,例如GMT-09:30GMT+08:00这样的以 "GMT" 开头的表征偏移字符串,也可以为 IANA 标识,如Asia/ShanghaiAmerica/Los_Angeles等。
当你使用数字或 GMT-09:00 类似写法时,Semi 内部会将这些时区标识转换为 IANA 标识。
  • 如设置 -9GMT-09:00 时,会转换成 Pacific/Gambier。某些数字对应的 IANA 标识可能有多个,Semi 首选无夏令时的 IANA 标识;
  • 如果该数字没有对应的无夏令时 IANA 标识,如 -3.53.510.513.75,这时我们映射的就是一个有夏令时的 IANA 标识,有夏令时的时区会在偏移量上进行调整,如 -3.5 会在进入夏令时后在标准时间上增加 1h。
如果你想准确设置一个地区的时区,推荐使用 IANA 标识而不是前面的用法。这里可以查看 IANA 标识列表,以及时区是否有夏令时。

FAQ

  • ConfigProvider中没有提供全局自定义prefix classname的功能,有类似需求如何实现(例如SDK中使用了Semi,期望打包的dom样式不带.semi-xx前缀,以免被宿主的全局 CSS 影响)?
    • 由于 prefixCls 需要同时被组件层的 js/css 消费,Semi 将此开关放在了webpack plugin的配置项中,而不是作为ConfigProvider的配置项。
    • 如果你使用webpack,请在SemiWebpackPlugin的参数中进行配置

semiGlobal

除了 ConfigProvider外,你还可以通过 semiGlobal 配置覆盖全局组件的默认 Props。该能力在 v2.59.0后提供
semiGlobal.config.overrideDefaultProps 可配置组件默认 Props,你需要将你的配置放到整个站点的入口处,即优先于所有 Semi 组件执行。
注意事项
semiGlobal 是单例模式,会影响整个站点,如果你只想覆盖某些地方的某些组件 Props ,建议不要使用 semiGlobal,而是将对应需要覆盖的组件封装一层并传入修改后的默认 props。
比如下方配置就是将所有的 Button 默认设置为 warning,Select 的 zIndex 默认设置为 2000 等