使用场景 ​

覆盖配置分为两种场景

  • 需要覆盖多个组件公有 Props 配置（例如 timezone、rtl），使用 ConfigProvider
  • 当 ConfigProvider 暴露参数未能满足，希望修改全局修改某个组件的 某类 Props（例如期望将所有Button的 theme 都配置为 solid 或所有 Popover的 zIndex），使用 semiGlobal

ConfigProvider ​

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

代码演示 ​

如何引入 ​

jsx
import { ConfigProvider } from '@kousum/semi-ui-vue';

基本用法 ​

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

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多语言配置，同LocaleProvider中locale参数的用法（如果同时在ConfigProvider和LocaleProvider中配置locale，前者优先级高于后者）object
timeZone时区标识string|number

时区标识 ​

  • 数字，例如 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 会在进入夏令时后在标准时间上增加 1h。

如果你想准确设置一个地区的时区，推荐使用 IANA 标识而不是前面的用法。这里可以查看 IANA 标识列表，以及时区是否有夏令时。

FAQ ​

  • ConfigProvider中没有提供全局自定义prefix classname的功能，有类似需求如何实现（例如SDK中使用了Semi，期望打包的dom样式不带.semi-xx前缀，以免被宿主的全局 CSS 影响）？
    • 由于 prefixCls 需要同时被组件层的 js/css 消费，Semi 将此开关放在了webpack plugin的配置项中，而不是作为ConfigProvider的配置项。
    • 如果你使用webpack，请在SemiWebpackPlugin的参数中进行配置
diff
# webpack配置示例
const SemiWebpackPlugin = require('@douyinfe/semi-webpack-plugin').default;
module.exports = {
+    plugins: [new SemiWebpackPlugin({ prefixCls: 'imes' })],
}

semiGlobal ​

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

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

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

比如下方配置就是将所有的 Button 默认设置为 warning，Select 的 zIndex 默认设置为 2000 等

js
import { semiGlobal } from "@douiyinfe/semi-ui";

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