@douyinfe/semi-ui
Version:
A modern, comprehensive, flexible design system and UI library. Connect DesignOps & DevOps. Quickly build beautiful React apps. Maintained by Douyin-fe team.
287 lines (201 loc) • 13.4 kB
Markdown
---
category: 生态与帮助
title: Update 从 1.x 到 2.0
icon: doc-updateV2
localeCode: zh-CN
order: 17
---
### 升级准备
请将你当前所有已修改的代码提交，checkout 出单独的 git 分支，保证 git 工作区干净
### 开始升级
### 安装 Semi 2.0
```bash
npm i /semi-ui
```
### 修改代码
对涉及到 breaking change 的代码进行修改，你可以手动对照下方[不兼容列表](/zh-CN/start/update-to-v2#2.0%20%E6%9C%89%E5%93%AA%E4%BA%9B%E4%B8%8D%E5%85%BC%E5%AE%B9%E7%9A%84%E5%8F%98%E5%8C%96)逐条检查代码进行修改。
另外我们也提供了一个 codemod cli 工具以帮助你快速升级到 2.0 版本
##### 1.全局安装自动升级工具:
```bash
npm i /semi-codemod-v2 -g # bnpm源
```
##### 2.使用 semi-codemod-v2 对项目代码进行扫描，并对 breaking change 进行自动修改
若你希望了解 codemod具体做的自动变更范围，可以查看[这篇文档](https://github.com/DouyinFE/semi-design/wiki/About-semi-codemod-v2)
```
semi-codemod-v2 <ProjectPath> [options]
// options:
// --dry, Dry run (no changes are made to files) 是否只运行而不将实际修改写入文件
// --force, Whether ignore git status; 为 true 时将不检查 git 工作区是否干净
// --verbose=2, Log level, optional: 0/1/2, default: 0 日志级别
```
| 使用示例 | 需执行命令 |
| --- | --- |
| 当希望扫描并升级整个项目的所有文件时<br/>(项目路径为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` |
<br/>
```
// 命令行 Result 输出说明
Results:
0 errors // 运行该转换规则，但在执行替换过程发生了错误的文件个数
13 unmodified // 符合该条匹配规则，但没有进行修改（即使用了该组件，但没有涉及到相关废弃的API）的文件个数
158 skipped // 不符合该条匹配规则，已跳过的文件个数
4 ok // 共有4个文件符合替换规则，cli已进行了自动修改
Time elapsed: 5.398seconds
```
##### 3.对于可识别但无法自动修改的部分，codemod 会在命令行进行提示，抛出 warning，你需要建议按提示手动修改
所有 warning 日志会在 ProjectPath 下 semi-codemod-log.log 文件进行输出，你可以按照log日志逐条检查修改
##### 4.更新 CSS Variable 的使用方式
若你在代码中使用了 Semi 的 CSS Variable，除了需要使用 semi-codemod-v2 外，你还需要使用我们提供的 style-lint 工具，对所有 CSS Variable 的使用进行自动更新
- 安装 Semi style-lint 包
```bash
# 需指定 npm 源为 bnpm
npm i -D /stylelint-semi@2.0.0-alpha.1
```
- 创建或修改 `.stylelintrc.json` 文件
```json
{
"plugins": ["@ies/stylelint-semi"],
"rules": {
"semi/css-token-migrate": [true, { "severity": "warning" }]
}
}
```
- CSS Token 从 1.x 升级为 2.x
```bash
# "**/*.scss" 或者其他文件/目录，可以处理 JSX、TSX、CSS、SCSS、LESS 等格式的文件
npx stylelint "**/*.scss" --fix // 处理scss中的 CSS 变量
npx stylelint "**/*.tsx" --fix // 处理tsx中的内联style中的 CSS 变量
npx stylelint "**/*.jsx" --fix // 处理jsx中的内联style中的 CSS 变量
```
> 自动替换依赖 stylelint，仅替换在样式文件或 style 属性里的颜色变量（引用的值不会替换），建议替换后全局搜索一下没有替换干净的地方
```
// replace '--amber-0' to '--semi-amber-0'
const searchReg = /--((amber|black|blue|cyan|green|grey|indigo|light|lime|orange|pink|purple|red|teal|violet|yellow|white|color|shadow|overlay|border|gray)(-[a-z\d]+)*)/;
const replaceReg = /--semi-$1/;
```
##### 5.更新主题包
若你的项目中使用了自定义主题包，需要前往 [Semi DSM](https://semi.design/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](https://bytedance.feishu.cn/docs/doccnOIgRqiqeBkhYzro1Bmvd8e#)），codemod 的自动修改/检测可能不能覆盖所有场景。如果发现有 codemod未覆盖的case，可以拉起oncall进行反馈。
请对所有涉及改动的页面进行回归测试。
## 2.0 有哪些不兼容的变化
### 🎁 包名的调整
v2.0 Semi 正式开源发布至公网 npm，包名需要调整，去除原有的 `` 前缀，更新为 `` 前缀。
### 🔍 import 路径变化
#### 引入组件
```text
// before
import { Select, Input, Form } from '/semi-ui-react';
// after
import { Select, Input, Form } from '/semi-ui';
```
#### 引入 interface（TypeScript 项目）
所有 Interface 的相关变更可查阅 [Semi 1.x -> 2.0 TS interface变更详细记录](https://bytedance.feishu.cn/docs/doccn5abrdIWvXO7No0Wkh8zo4b)
```text
// before
import { SelectProps } from '/semi-ui-react/select';
// now
import { SelectProps } from '/semi-ui/lib/es/select';
```
#### 引入 locale 资源文件
```text
// before
import en_GB from '/semi-ui-react/locale/source/en_GB';
// now
import en_GB from '/semi-ui/lib/es/locale/source/en_GB';
```
### 🛠 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
- Banner icon、closeIcon不再支持string，需要替换为对应的ReactNode
- Typography.Text的icon不再支持string，需要替换为对应的ReactNode
- Breadcrumb.Item的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 }}`。
- Icon 组件的共有className 由 `semi-icons` 变更为 `semi-icon`，对齐组件命名
### 插件调整
如果你使用 Semi 插件，如 `/semi-ui-plugin-webpack` 或 `@ies/semi-ui-plugin-eden` 等进行了高级配置，需要了解以下变更：
- svg 相关
- 2.x 不再支持 iconLazyLoad （因为已经支持Shaking）
- svgPaths、srcSvgPaths 配置不再支持，你可以通过使用 svgr webpack 插件作为替换，详细可参考 [Icon组件](/zh-CN/basic/icon#%E4%BD%BF%E7%94%A8svgr%E5%B0%86svg%E6%96%87%E4%BB%B6%E8%BD%AC%E6%88%90ReactComponent)
- 暗色模式相关
- 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 使用调整：
```text
// 1.x 默认 iconLazyload 为 false 的情况
<Icon type="home" />;
// 1.x 当 iconLazyload 为 true 的情况
import homeSvg from '/semi-icons/semi-icons-home.svg';
<Icon type={homeSvg.id} />;
// 2.x 统一使用如下方式使用
import { IconHome } from '/semi-icons';
<IconHome />;
```
插画使用调整：
```text
// 1.x
import { Empty } from '/semi-ui-react';
import Construction from '/semi-illustrations/construction.svg';
<Empty image={Construction} />;
// 2.x
import { Empty } from '/semi-ui';
import { IllustrationConstruction } from '/semi-illustrations';
<Empty image={<IllustrationConstruction />} />;
```
#### Design Token 调整
| 组件 | Sass 变量 | 调整前 | 调整后 |
| --- | --- | --- | --- |
| Popconfirm | \$color-popconfirm_body-text | var(--semi-color-tertiary) | var(--semi-color-text-2) |
| | \$color-popconfirm_header_alert-icon | #fa7500 | var(--semi-color-warning) |
| Progress | \$spacing-progress_line_text-marginLeft | 15px | \$spacing-base |
| | \$spacing-progress_line_text-marginRight | 15px | \$spacing-base |
| Radio | \$spacing-radio_addon_buttonRadio_large-paddingY | 6px | \$spacing-base-tight / 2 |
| | \$radius-radio_cardRadioGroup | 3px | var(--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 导致，这一状况导致，原有的插画左右多了空白，不太符合预期。
### 其他与字节内部框架的兼容问题？
字节跳动用户，请查阅对应[飞书文档](https://bytedance.feishu.cn/docx/doxcnkrOpKFwK9ugkkcfAsUJqYd)
## 遇到问题
我们列出了已知的所有不兼容变化和相关影响，但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题，欢迎随时通过客服群进行反馈沟通