--- category: 开始 title: Update 从 1.x 到 2.0 icon: doc-updateV2 localeCode: zh-CN order: 15 --- ### 升级准备 请将你当前所有已修改的代码提交，checkout 出单独的 git 分支，保证 git 工作区干净 ### 开始升级 ### 安装 Semi 2.0 ```bash npm i @douyinfe/semi-ui@latest ``` ### 修改代码 对涉及到 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 [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 日志级别 ``` | 使用示例 | 需执行命令 | | --- | --- | | 当希望扫描并升级整个项目的所有文件时
(项目路径为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](https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/codemod.gif) ``` // 命令行 Result 输出说明 Results: 0 errors // 运行该转换规则，但在执行替换过程发生了错误的文件个数 13 unmodified // 符合该条匹配规则，但没有进行修改（即使用了该组件，但没有涉及到相关废弃的API）的文件个数 158 skipped // 不符合该条匹配规则，已跳过的文件个数 4 ok // 共有4个文件符合替换规则，cli已进行了自动修改 Time elapsed: 5.398seconds ``` ##### 3.对于可识别但无法自动修改的部分，codemod 会在命令行进行提示，抛出 warning，你需要建议按提示手动修改 ![warning](https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/waringDemo.png) 所有 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/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/; ``` ![VS Code token replace](https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/vscode-semi-token-replace.png) ##### 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，包名需要调整，去除原有的 `@ies` 前缀，更新为 `@douyinfe` 前缀。 ### 🔍 import 路径变化 #### 引入组件 ```text // before import { Select, Input, Form } from '@ies/semi-ui-react'; // after import { Select, Input, Form } from '@douyinfe/semi-ui'; ``` #### 引入 interface（TypeScript 项目） 所有 Interface 的相关变更可查阅 [Semi 1.x -> 2.0 TS interface变更详细记录](https://bytedance.feishu.cn/docs/doccn5abrdIWvXO7No0Wkh8zo4b) ```text // before import { SelectProps } from '@ies/semi-ui-react/select'; // now import { SelectProps } from '@douyinfe/semi-ui/lib/es/select'; ``` #### 引入 locale 资源文件 ```text // before 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'; ``` ### 🛠 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 插件，如 `@ies/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 图标。在便捷使用的同时，也带来了一些问题：icon 默认全量引入，无法被 shaking；svg-sprite-loader 与 Webpack 强绑定，无法便捷地支持 Rollup、Vite 等其他构建方案。因此 2.0 中，我们去除了与 svg-sprite-loader 的强绑定，Icon 的消费方式需要变更： Icon 使用调整： ```text // 1.x 默认 iconLazyload 为 false 的情况 ; // 1.x 当 iconLazyload 为 true 的情况 import homeSvg from '@ies/semi-icons/semi-icons-home.svg'; ; // 2.x 统一使用如下方式使用 import { IconHome } from '@douyinfe/semi-icons'; ; ``` 插画使用调整： ```text // 1.x import { Empty } from '@ies/semi-ui-react'; import Construction from '@ies/semi-illustrations/construction.svg'; ; // 2.x import { Empty } from '@douyinfe/semi-ui'; import { IllustrationConstruction } from '@douyinfe/semi-illustrations'; } />; ``` #### 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) ## 遇到问题 我们列出了已知的所有不兼容变化和相关影响，但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题，欢迎随时通过客服群进行反馈沟通