|
|
@@ -6,20 +6,122 @@ localeCode: zh-CN
|
|
|
order: 6
|
|
|
---
|
|
|
|
|
|
-## 开始升级
|
|
|
-
|
|
|
### 升级准备
|
|
|
+
|
|
|
请将你当前所有已修改的代码提交，checkout 出单独的 git 分支，保证 git 工作区干净
|
|
|
|
|
|
+### 开始升级
|
|
|
+
|
|
|
### 安装 Semi 2.0
|
|
|
|
|
|
```bash
|
|
|
-npm i @douyinfe/semi-ui@2.0.0
|
|
|
+npm i @douyinfe/semi-ui@latest
|
|
|
```
|
|
|
|
|
|
### 修改代码
|
|
|
|
|
|
-请按照下方变更记录修改你的项目代码，Semi 将在 1 ~ 2周内推出迁移工具，帮助用户从 1.x 迁移至 2.x。
|
|
|
+对涉及到 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 @ies/semi-codemod-v2@latest -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 @ies/[email protected]
|
|
|
+```
|
|
|
+
|
|
|
+- 创建或修改 `.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 包安装至项目内
|
|
|
+
|
|
|
+##### 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 有哪些不兼容的变化
|
|
|
|
|
|
@@ -39,81 +141,85 @@ import { Select, Input, Form } from '@ies/semi-ui-react';
|
|
|
import { Select, Input, Form } from '@douyinfe/semi-ui';
|
|
|
```
|
|
|
|
|
|
+#### 引入 interface（TypeScript 项目）
|
|
|
|
|
|
-#### 引入 interface（TypeScript项目）
|
|
|
-
|
|
|
+所有 Interface 的相关变更可查阅 [Semi 1.x -> 2.0 TS interface变更详细记录](https://bytedance.feishu.cn/docs/doccn5abrdIWvXO7No0Wkh8zo4b)
|
|
|
```jsx
|
|
|
// before
|
|
|
-import { SelectProps } from '@ies/semi-ui-react/select'
|
|
|
+import { SelectProps } from '@ies/semi-ui-react/select';
|
|
|
|
|
|
// now
|
|
|
-import { SelectProps } from '@douyinfe/semi-ui/lib/es/select'
|
|
|
+import { SelectProps } from '@douyinfe/semi-ui/lib/es/select';
|
|
|
```
|
|
|
|
|
|
#### 引入 locale 资源文件
|
|
|
|
|
|
```jsx
|
|
|
// before
|
|
|
-import en_GB from '@ies/semi-ui-react/locale/source/en_GB'
|
|
|
+import en_GB from '@ies/semi-ui-react/locale/source/en_GB';
|
|
|
|
|
|
// now
|
|
|
-import en_GB from '@douyinfe/semi-ui/lib/es/locale/source/en_GB'
|
|
|
+import en_GB from '@douyinfe/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
|
|
|
-- 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 替换
|
|
|
+
|
|
|
+- 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 }}`。
|
|
|
+- 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。
|
|
|
+- 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 的消费方式需要变更：
|
|
|
+在 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 使用调整：
|
|
|
+
|
|
|
```jsx
|
|
|
// 1.x 默认 iconLazyload 为 false 的情况
|
|
|
-<Icon type="home" />
|
|
|
+<Icon type="home" />;
|
|
|
|
|
|
// 1.x 当 iconLazyload 为 true 的情况
|
|
|
import homeSvg from '@ies/semi-icons/semi-icons-home.svg';
|
|
|
-<Icon type={homeSvg.id} />
|
|
|
+<Icon type={homeSvg.id} />;
|
|
|
|
|
|
// 2.x 统一使用如下方式使用
|
|
|
import { IconHome } from '@douyinfe/semi-icons';
|
|
|
-<IconHome />
|
|
|
+<IconHome />;
|
|
|
```
|
|
|
|
|
|
插画使用调整：
|
|
|
@@ -122,39 +228,48 @@ import { IconHome } from '@douyinfe/semi-icons';
|
|
|
// 1.x
|
|
|
import { Empty } from '@ies/semi-ui-react';
|
|
|
import Construction from '@ies/semi-illustrations/construction.svg';
|
|
|
-<Empty image={Construction} />
|
|
|
+<Empty image={Construction} />;
|
|
|
|
|
|
// 2.x
|
|
|
import { Empty } from '@douyinfe/semi-ui';
|
|
|
import { IllustrationConstruction } from '@douyinfe/semi-illustrations';
|
|
|
-<Empty image={<IllustrationConstruction />} />
|
|
|
+<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) |
|
|
|
+| 组件 | 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）。
|
|
|
+
|
|
|
+在 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，是否可同时使用？
|
|
|
-由于Semi 2.0的包名与1.x并不相同，所以实际上他们会成了两个单独的包，互不影响。
|
|
|
+
|
|
|
+由于 Semi 2.0 的包名与 1.x 并不相同，所以实际上他们会成了两个单独的包，互不影响。
|
|
|
|
|
|
### CSS 变量添加 semi 前缀的原因？
|
|
|
-由于业务方微前端应用场景日渐增多，为避免与其他library css variable的命名冲突，规避样式互相影响问题。
|
|
|
+
|
|
|
+由于业务方微前端应用场景日渐增多，为避免与其他 library css variable 的命名冲突，规避样式互相影响问题。
|
|
|
|
|
|
### 为什么局部暗色/亮色模式由添加 id 改为添加 class？
|
|
|
+
|
|
|
id 具有语义上全局唯一的特点，class 则没有这个特点，使用 class 更符合规范。
|
|
|
|
|
|
### 为什么插画的尺寸有变化？
|
|
|
+
|
|
|
使用插画时，1.x 的插画宽高是 `300 * 150px`，是由于插画 svg 外层嵌套 svg 导致，这一状况导致，原有的插画左右多了空白，不太符合预期。
|
|
|
|
|
|
## 遇到问题
|
|
|
-我们列出了已知的所有不兼容变化和相关影响，但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题，欢迎随时通过客服群进行反馈沟通
|
|
|
+
|
|
|
+我们列出了已知的所有不兼容变化和相关影响，但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题，欢迎随时通过客服群进行反馈沟通
|
yanqi.xu