开始 · Update
从 1.x 到 2.0

升级准备

请将你当前所有已修改的代码提交,checkout 出单独的 git 分支,保证 git 工作区干净

开始升级

安装 Semi 2.0

修改代码

对涉及到 breaking change 的代码进行修改,你可以手动对照下方不兼容列表逐条检查代码进行修改。
另外我们也提供了一个 codemod cli 工具以帮助你快速升级到 2.0 版本
1.全局安装自动升级工具:
2.使用 semi-codemod-v2 对项目代码进行扫描,并对 breaking change 进行自动修改
若你希望了解 codemod具体做的自动变更范围,可以查看这篇文档
使用示例需执行命令
当希望扫描并升级整个项目的所有文件时
(项目路径为root/workspace/demo-project)
semi-codemod-v2 root/workspace/demo-project
只希望扫描并升级单个文件时semi-codemod-v2 root/workspace/demo-project/testFile.jsx
只希望扫描并升级单个文件时,但只希望将变更结果输出至 terminal,而不将实际修改写入文件时semi-codemod-v2 root/workspace/demo-project/testFile.jsx --dry

codemod
3.对于可识别但无法自动修改的部分,codemod 会在命令行进行提示,抛出 warning,你需要建议按提示手动修改
warning 所有 warning 日志会在 ProjectPath 下 semi-codemod-log.log 文件进行输出,你可以按照log日志逐条检查修改
4.更新 CSS Variable 的使用方式
若你在代码中使用了 Semi 的 CSS Variable,除了需要使用 semi-codemod-v2 外,你还需要使用我们提供的 style-lint 工具,对所有 CSS Variable 的使用进行自动更新
  • 安装 Semi style-lint 包
  • 创建或修改 .stylelintrc.json 文件
  • CSS Token 从 1.x 升级为 2.x
自动替换依赖 stylelint,仅替换在样式文件或 style 属性里的颜色变量(引用的值不会替换),建议替换后全局搜索一下没有替换干净的地方
VS Code token replace
5.更新主题包
若你的项目中使用了自定义主题包,需要前往 Semi DSM (即原 Semi 主题商店的升级版)进行 2.x 版本主题包的发布。并将新版主题 npm 包安装至项目内。 注意 Semi V1 的主题包 与 Semi V2 并不兼容,请务必重新发布。
6. 运行你的项目,进行dev构建。对抛出error的代码段 进行修改
由于 codemod 依赖 AST语法树进行分析并替换,不排除有依靠 AST 分析无法检测的情况。且由于我们在2.x版本进行了 TS重构,相关类型定义会比1.x更加严格。可能存在部分类型检查在 1.x能通过,在2.x无法通过编译的情况。 这类case在构建阶段会直接暴露,因此你可以case by case直接进行对应修改。
7.执行 git diff review 所有代码改动,回归相关页面
至此,你已完成所有升级步骤🥳
尽管我们尽可能地考虑了用户的使用场景,但仍不能排除会有遗漏或依靠 AST 分析无法检测的情况(当前已知的无法被检测或修改的Case),codemod 的自动修改/检测可能不能覆盖所有场景。如果发现有 codemod未覆盖的case,可以拉起oncall进行反馈。
请对所有涉及改动的页面进行回归测试。

2.0 有哪些不兼容的变化

🎁 包名的调整

v2.0 Semi 正式开源发布至公网 npm,包名需要调整,去除原有的 @ies 前缀,更新为 @douyinfe 前缀。

🔍 import 路径变化

引入组件

引入 interface(TypeScript 项目)

所有 Interface 的相关变更可查阅 Semi 1.x -> 2.0 TS interface变更详细记录

引入 locale 资源文件

🛠 API 相关的调整

  • Icon 相关
    • Icon 组件不再支持 type=xxx 方式使用内置 icon
    • 自定义 svg 不再支持插件方式配置 srcSvgPaths
    • Button icon 属性不再支持通过 string 传递内置 icon 或 iconType
    • Dropdown 删除 iconType 属性,统一为 icon 属性
    • Navigation
      • Nav.item 组件, Nav.Sub 组件 props.icon 不再支持通过 string 方式传入,需要传入 ReactNode
      • Nav 组件 props.items 中的 icon 也不再支持通过 string 方式传入,需要传入 ReactNode
    • Notification icon 不再支持通过 string 方式传入,请统一使用 ReactNode
  • AutoComplete 正式废弃 onChangeWithObject 属性
  • Cascader triggerRender 的入参移除 onInputChange
  • Form 不再从 semi-ui/index.js 导出 Label 组件,如需使用请用 Form.Label
  • Tree onRightClick 更名为 onContextMenu
  • Upload dragable 更名为 draggable
  • Tooltip 不再支持 disabled 属性,依赖 Tooltip 的组件(如 Popover、Dropdown 等)透传给 Tooltip disabled 将失效
  • Table
    • 不再在 componentDidUpdate 时响应的 API
      • defaultExpandAllRows,请用 expandAllRows 替换
      • defaultExpandRowKeys,请用 expandRowKeys 替换
      • defaultExpandAllGroupRows,请用 expandAllGroupRows 替换

🎨 样式上的不兼容

  • CSS 变量添加 semi 前缀,例如 --color-primary => --semi-color-primary
    • 使用了 Semi CSS Variable 来实现暗色模式等特性的用户,需要将自定义 CSS 中的 variable 统一进行更新
    • 未在自定义组件或页面的中使用 Semi CSS Variable 的用户无需关注,不受影响
  • 在 2.x,统一将插画的宽高设置为 200 * 200px,如果想模拟 1.x 的宽高,可以给插画设置 style={{ width: 300, height: 150 }}

插件调整

如果你使用 Semi 插件,如 @ies/semi-ui-plugin-webpack@ies/semi-ui-plugin-eden 等进行了高级配置,需要了解以下变更:
  • svg 相关
    • 2.x 不再支持 iconLazyLoad (因为已经支持Shaking)
    • svgPaths、srcSvgPaths 配置不再支持,你可以通过使用 svgr webpack 插件作为替换,详细可参考 Icon组件
  • 暗色模式相关
    • 2.x 默认已支持局部暗色模式、亮色模式,不再需要在插件配置 themeScope 属性。使用方式由添加 id #semi-always-xxx 更新为添加 class .semi-always-xxx。

其他调整

Icon/插画使用调整

在 0.x/1.x 版本的 Semi 中,我们强依赖 svg-sprite-loader 将 svg 文件转换为 svg symbol 并在运行时插入 body,使得我们可以仅通过 <Icon type='xxx' / > 以字符串的方式去使用 Icon 图标。在便捷使用的同时,也带来了一些问题:icon 默认全量引入,无法被 shaking;svg-sprite-loader 与 Webpack 强绑定,无法便捷地支持 Rollup、Vite 等其他构建方案。因此 2.0 中,我们去除了与 svg-sprite-loader 的强绑定,Icon 的消费方式需要变更:
Icon 使用调整:
插画使用调整:

Design Token 调整

组件Sass 变量调整前调整后
Popconfirm\$color-popconfirm_body-textvar(--semi-color-tertiary)var(--semi-color-text-2)
\$color-popconfirm_header_alert-icon#fa7500var(--semi-color-warning)
Progress\$spacing-progress_line_text-marginLeft15px\$spacing-base
\$spacing-progress_line_text-marginRight15px\$spacing-base
Radio\$spacing-radio_addon_buttonRadio_large-paddingY6px\$spacing-base-tight / 2
\$radius-radio_cardRadioGroup3pxvar(--semi-border-radius-small)

FAQ

为什么引用路径发生了变化?

在 1.x 中,Semi 采用源码发布的方式,执行 npm publish 前不会执行预编译,组件库的 Scss、jsx/js 会跟随业务代码一同进行编译,2.0 中 npm publish 前进行了预编译,对于普通用户来说,预编译可以让 Semi 做到开箱即用:无需让用户编译 Semi 源文件,无需在使用时引入 Semi 插件。由于编译后的结果在 lib/es 下,因此接口和语言包的引用路径发生了变化,但对于组件引用,你无需改变原有的引用路径(因为 package.json main 属性指向 lib/es/index.js)。

项目希望升级至 2.0,但项目中使用了 Semi 物料,物料基于 1.x Semi,是否可同时使用?

不可以,semi2.x的css类名与semi1.x的相同,同时使用会导致样式冲突。如遇到类似问题,请在飞书群里发起oncall,会有专人对接处理。

CSS 变量添加 semi 前缀的原因?

由于业务方微前端应用场景日渐增多,为避免与其他 library css variable 的命名冲突,规避样式互相影响问题。

为什么局部暗色/亮色模式由添加 id 改为添加 class?

id 具有语义上全局唯一的特点,class 则没有这个特点,使用 class 更符合规范。

为什么插画的尺寸有变化?

使用插画时,1.x 的插画宽高是 300 * 150px,是由于插画 svg 外层嵌套 svg 导致,这一状况导致,原有的插画左右多了空白,不太符合预期。

其他与字节内部框架的兼容问题?

字节跳动用户,请查阅对应飞书文档

遇到问题

我们列出了已知的所有不兼容变化和相关影响,但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题,欢迎随时通过客服群进行反馈沟通