开始 · 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 包安装至项目内
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、svgPaths、srcSvgPaths 配置;
  • 暗色模式相关
    • 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、Snowpack 等其他构建方案。因此 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 导致,这一状况导致,原有的插画左右多了空白,不太符合预期。

遇到问题

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

© 2021 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED