企业官网建设流程全解析

UI 组件库的数量越来越多，团队在选型和迁移时最痛苦的不是组件好不好用，而是不同组件库之间根本没有统一语言：这个库叫Button，那个库叫Button，但 props、事件、插槽、样式体系全都不一样。把一套已经写好的页面从 A 组件库换到 B 组件库，表面上只是改标签名，实际上要把整个组件使用习惯重学一遍。这个项目用“罗塞塔石碑”的思路，把多个 UI 组件库之间的对应关系整理成可对照、可检索的映射资源，解决的就是“跨组件库翻译”这件事。

这篇文章适合正在做组件库迁移、需要维护多套前端项目、或者在选型阶段想快速评估多个组件库差异的开发者。最值得关注的点不是它能把代码自动转换，而是它提供了一套按组件、按 API、按行为拆解的对照方法。下面我会按实际落地顺序，讲清楚这类“UI 组件库罗塞塔石碑”到底怎么用、能解决到哪一步、哪些地方又会踩坑。

1. 为什么 UI 组件库之间需要一份对照表

1.1 每个组件库都有一套“自己的方言”

一个组件库通常包含按钮、输入框、弹窗、表格、表单、选择器、日期控件等几十个基础组件，再加上布局、反馈、导航这些扩展组件。听起来都是同一批东西，但每一家实现都不一样。

差异常见在几个层面。

组件名称不同。同一个“开关”，有的叫Switch，有的叫Toggle；同一个“分割面板”，有的叫SplitPane，有的叫Resizer。只看名字很难判断。

Props 不同。控制禁用状态，A 组件库用disabled，B 组件库可能用isDisabled，C 组件库甚至用is-disabled。控制加载状态，常见写法有loading、spinner、loadingText三种。

事件不同。关闭弹窗，有的触发close事件，有的触发cancel，有的触发visibleChange。日期选择器更是重灾区，change、confirm、select、update:value混在一起。

插槽和子元素机制不同。Vue 组件库普遍依赖插槽，React 组件库大量使用 children 和 render prop，Angular 组件库又走 content projection。三套思路放在一起，就不是简单改名字能解决的。

这些差异堆在一起，导致两个很现实的问题：第一，迁移一个页面，看起来只改了十几个组件，实际要逐个确认 API 和行为；第二，团队里如果同时存在两套技术栈，光沟通成本就很高。

1.2 对照表的本质是降低“翻译成本”

“罗塞塔石碑”这个项目想做的事很简单：把不同组件库的同义组件并排列出来，让开发者像查字典一样找到对应关系。

但这并不容易做好。因为组件不是简单的词汇对应，它是一组语义、接口、样式和交互行为的集合。真正的对照表至少要包含：

• 组件名称对应关系
• 组件用途和适用场景
• 主要 Props / API 对应关系
• 事件和回调对应关系
• 插槽、子元素、渲染方式差异
• 样式体系和主题定制差异
• 行为细节差异，比如焦点管理、键盘交互、无障碍支持
• 迁移难度和注意事项

有了这样一张表，开发者就不用同时打开六七个组件库文档来回切换，也不用靠搜索引擎拼凑零散答案。它能帮你在选型阶段快速看到“B 组件库是否覆盖现有项目的高频组件”，也能在迁移阶段直接定位到具体组件和具体参数的差异。

1.3 它不能替代代码转换工具

这里要先把边界说清楚。网上经常有人希望这类工具能一键把项目从组件库 A 自动迁移到组件库 B，比如自动替换标签、自动改名。以我实测很多迁移工具的经验来看，彻底自动化很难成立。

原因是组件迁移不只是改标签名，还涉及 props 的合并拆分、事件名称的变更、样式类名的重写、逻辑代码的调用调整，以及很细节的默认值差异。机器人能改 70%，剩下 30% 反而最难处理，因为错误藏在行为差异里。

所以我对这个项目的定位是：它是一份高质量参考手册，一个辅助迁移的“翻译对照表”，不是万能的自动迁移器。用的时候思路要清楚：先靠对照表确定方向和参数，再靠人工修改和测试收尾。

2. 使用前先做好四类前置准备

2.1 明确你的源组件库和目标组件库

所有对照关系都源于特定版本。同一个组件库，2.x 和 3.x 可能连引入路径都不一样，更不用说 API 设计。所以使用前第一件事就是记录：

• 源组件库名称和版本
• 目标组件库名称和版本
• 项目框架，比如 Vue 2、Vue 3、React 16 还是 React 18
• 是否使用 TypeScript，以及严格程度
• 构建工具和样式方案，比如 CSS Modules、Tailwind、styled-components

版本不锁定，后面所有对照都会漂移。

2.2 先盘点业务里真正用到的组件

不要一上来就把两个组件库全部组件做对照，那样工作量巨大，而且很多对照根本用不上。先盘点当前项目里实际使用的组件。

我一般会用一个简单方法：在组件库入口处检索import或全局注册记录，把用到的组件名和出现次数统计出来。重点关注高频组件，比如Button、Input、Select、Table、Modal、Form、DatePicker、Tabs。

统计完成后，你通常会发现 80% 的业务页面只用到 20 个左右的核心组件。把这 20 个放在对照表最前面，其余组件按需补充，不追求一次覆盖全部。

2.3 准备一套可复现的验证环境

对照表里的信息不能只看文档，一定要跑起来验证。建议准备一个小型 Demo 项目，只包含最典型的页面，比如：

• 一个带搜索条件的表格页
• 一个带表单向导的弹窗
• 一个带步骤条和选项卡的详情页
• 一个处理日期范围和选择器的筛选面板

每个页面都用源组件库写一遍，再按对照表手动迁移到目标组件库。这样才能发现文档里没有写的坑。

2.4 约定好记录模版

如果没有统一模版，对照表很快就会变成一堆杂乱笔记。建议至少包含以下字段：

记录模版确定后，再补内容，效率会高很多。否则上午做几个组件，下午就容易被细节淹没。

3. 把组件映射表真正建出来

3.1 按“组件用途”而不是“组件名”查找对应

很多人建对照表时犯的第一个错误是：拿源组件的名字去目标组件库里搜同名组件，搜到就觉得对应上了。这个思路不完全对。

罗塞塔石碑的价值恰恰在于“语义对齐”。你需要先想清楚源组件在页面里承担什么职责，然后再去目标组件库里找同类职责的组件。

举个例子，有的组件库把“下拉菜单”拆成Dropdown、Menu、Select三个组件，而另一个组件库可能只有Dropdown和Select。如果两个Dropdown看似同名，实际一个负责命令菜单，一个负责选择器，直接替换就会出现功能错位。

更常见的是“消息提示”这类组件。有的库提供全局方法Message.success()，有的库提供一个<Notification>组件，还有的库要求开发者在业务代码里自己控制状态。这三者名称完全不一样，但业务用途都是“给用户展示操作反馈”。所以映射关系应该是“消息提示这个功能场景”对应到不同库的不同实现，而不是简单组件名互换。

3.2 逐个 API 拆开对照

确定组件级映射后，开始拆 API。这个步骤最繁琐，也最关键。拿一个典型的Table表格组件来说，至少要看这些方面：

• 数据源字段名：data、rows、datasource还是items
• 列定义方式：columns数组、slot、还是 JSX 配置
• 自定义单元格：插槽、render function、children 回调
• 排序和筛选：受控还是非受控，回调参数是什么结构
• 分页：自带分页还是业务端接管，分页器字段叫什么
• 选择行：rowSelection、selectedRows、@selection-change等形式差异
• 合并单元格：API 差异非常大，通常需要额外配置
• 加载状态：loading、v-loading、spinner等差异
• 空数据提示：默认有无，能不能自定义

把每个 API 拆出来打成表格，一行一行标出来：

这个过程能让你提前发现迁移量有多大。如果一个页面里大量使用表格自定义单元格，迁移成本就会明显上升，不能只盯着组件名做替换。

3.3 事件和回调要按“触发的时机”对齐

事件对应关系往往最隐蔽。两个组件库都有change事件，但触发时机可能完全不同。一个是在每次输入时触发，一个是在失焦时触发。如果业务代码依赖这个时机，迁移后就会出现隐性 bug。

整理事件时，我建议不要只看事件名，而是记录事件触发时机和回调参数。比如：

• 源组件Select的change在选中项变化时触发，参数是新值；
• 目标组件Select的change在用户点击确认时触发，参数是完整选项对象。
• 如果迁移后还按旧参数处理，很容易取到undefined。

还有一类问题在 Vue 项目中非常典型：v-model与.sync的差异。同一个组件，在 Vue 2 里可能是:visible.sync，在 Vue 3 里可能是v-model:visible。虽然框架层面有转换方式，但组件库的默认值和行为可能不同。要用对照表把这类“语法糖差异”明确标出来，否则迁移时会出现组件不响应的问题。

3.4 样式和主题的对照是独立维度

有些组件库从设计上就绑定了设计语言，比如间距、圆角、阴影、边框、字体都有固定 token。另一个组件库则非常克制，只提供基础结构和 CSS 变量。

迁移到这种组件库时，业务表现会立刻变化。明明组件功能都正常，页面就是“看着不对”。

所以对照表里必须加上样式维度。至少记录：

• 是否有预置主题，默认主题是什么风格
• 自定义主题方式：CSS 变量、Less/Sass 变量、Design Token、还是运行时变量覆盖
• 类名前缀是否可以配置
• 是否高度依赖全局样式文件
• 是否有 reset、normalize 之类的样式副作用

我见过不少项目卡在样式这一步。组件代码已经全改完了，但页面颜色、间距、字体层级全部对不上。最稳妥的做法是在对照表里直接记录目标组件库的主题变量映射，把源项目里的品牌色、主色调、成功色、警告色、错误色、圆角、间距逐项对应过去，而不是迁移完再凭感觉调。

3.5 用页面样例反推对照表准确性

对照表建到一定规模后，拿真实页面样例验证是必须的。建议选一个中等复杂度的页面，按照对照表完整迁移一遍，然后逐项检查：

• 页面渲染是否成功
• 所有事件是否按预期触发
• 表单校验是否生效
• 键盘操作和无障碍表现是否一致
• 不同屏幕尺寸下布局是否正常
• 主题和样式是否保持一致

通过这个过程，你很快会发现哪些映射写错了，哪些行为差异没考虑到。把这些问题回填到对照表，这张表才会越来越可靠。

4. 用对照表驱动真实迁移流程

4.1 先做“可删除式”改造，不要原地重写

拿到一份比较完整的对照表后，不要立刻在大项目里大范围替换。我建议先把迁移分成三层：基础设施层、组件封装层、业务页面层。

基础设施层通常包括：组件库入口文件、全局样式、主题配置、按需加载设置、全局方法和工具函数。

组件封装层指的是业务组件，比如ListPage、SearchForm、DetailModal。这些组件是在基础组件上再封装的一层，迁移时优先改这里，业务页面可以先不动。

业务页面层最杂，历史代码多，直接改动风险大。比较稳的顺序是：

1. 更换组件库依赖和入口配置。
2. 把基础组件封装层迁移过去。
3. 找一个高频页面做试点。
4. 验证稳定后，再批量替换其余页面。

批量替换时，要确保能快速回滚。不要一次性提交几百个文件，否则出了问题很难定位。

4.2 建立“迁移批次”和验收标准

组件库迁移不是写作文，不能靠感觉“差不多”。每个批次都要有明确验收标准。

我常用的验收清单：

• 页面能正常打开，控制台无报错
• 核心交互能完成，比如查询、新增、编辑、删除、翻页
• 表单能正确提交和校验
• 弹窗开关和遮罩行为正常
• 表格列宽、自定义单元格、排序、分页正常
• 主题色和间距与设计稿一致
• 浏览器兼容性抽查正常
• 无资源加载 404

每跑完一批，就在对照表里更新验证状态。这样就算团队换人，也能知道哪些组件还处于“待验证”状态。

4.3 遇到无法映射的组件时先冻结需求

实际迁移时总会遇到目标组件库没有对应组件的情况。比如源组件库提供了Timeline时间轴，目标组件库没有；或者目标组件库的版本里TreeSelect还不够成熟。这时候有两个选择：用一个更基础的组件自行封装，或者暂时保留源组件库的局部模块。

我通常建议先冻结这个组件的迁移计划，不强行用功能不对等的组件顶替。原因很简单：业务功能已经用了组件库 A 的成熟能力，贸然换成勉强替代的新组件，页面稳定性和开发成本都不可控。先把高频、必须迁移的组件处理完，再单独评估这些“孤儿组件”。

在对照表里给这些组件标成“暂缓迁移”，要比硬着头皮迁移更务实。

4.4 控制迁移过程中的技术债

迁移过程中，最常见的偷懒方式是为了减少改动，在业务页面里写大量兼容代码。比如写一个内部组件同时接收两个组件库的 props，或者通过if判断当前使用哪个库。做几个还好，做多了就会让项目变得很难维护。

所以迁移时要规定：业务页面只能使用目标组件库的 API，不允许再出现源组件库的调用方式。封装层如果需要兼容，也要单独建目录，标注清楚“迁移过渡代码”，并且要有一份计划在什么时候彻底删掉。

这条规则一开始可能影响开发速度，但长期看是值得的。否则项目会同时背着两套组件库的心智负担，团队协作成本大幅上升。

5. 高频坑位与排查顺序

5.1 组件不显示，先看导入路径和版本

迁移后页面空白或组件不渲染，最常出现在三个地方：

• 组件导入路径写错。有些组件库Table和Table.Column的导入路径不同，有些又使用子组件注册，漏写就会渲染失败。
• 版本不匹配。目标组件库的主版本和项目框架不匹配，比如 Vue 2 项目里装了只支持 Vue 3 的版本，页面无法启动。
• 全局样式没有引入。很多组件库要求引入基础样式文件，比如dist/index.css或theme-chalk/index.css，漏掉后组件虽然能渲染，但完全没样式，看起来像坏掉。

排查顺序建议是：先看浏览器控制台是否有 JS 报错，再看网络请求里对应资源是否加载，最后检查组件库的版本兼容性。不要直接怀疑业务代码。

5.2 弹窗和表单不联动，先看受控和非受控

组件库迁移后最容易出现“弹窗打不开”“表单值不更新”这种问题。这通常不是事件绑定失败，而是受控模式和非受控模式的差异。

有的组件库全组件可控，比如visible和onClose都由外部控制；有的组件库则自己维护内部状态，外部只传defaultVisible。如果你在源组件库里习惯传defaultVisible，迁移到目标组件库后可能完全不生效，因为目标库只认visible。

排查这类问题要按这个思路：

1. 确认组件是受控还是非受控
2. 确认绑定属性名是否一致，比如visible、value、modelValue
3. 确认事件是否返回了最新值
4. 确认是否存在v-model与.sync的语法差异

这类问题用对照表最容易发现，因为对照表里如果明确写了“受控 / 非受控”、“用的是 v-model 还是 props + events”，踩坑率会低很多。

5.3 表格列配置不生效，先看列定义是对象还是函数

表格是业务系统里最复杂的组件。迁移后经常出现“列没显示”“自定义单元格渲染不出来”的情况。大部分原因是列定义方式不同。

一个组件库可能支持columns: [{ title, dataIndex, render }]，另一个组件库可能支持columns: () => [{ title, key, render }]。函数式列定义可以访问当前作用域，动态性很强；对象式列定义更静态，写法简单，但自定义能力受限。

如果迁移后的列定义突然不能使用某个变量，很大概率是列定义类型变化了。排查时先打印columns，确认它是数组还是函数，再按对应方式调整。

5.4 样式对不上，先查 CSS 变量和主题覆盖

如果组件渲染了、功能也正常，唯独颜色、间距和设计稿不一致，那基本是主题系统的问题。很多组件库的默认主题并不适合业务品牌，需要覆盖主题变量。

排查流程：

1. 检查目标组件库是否引入了默认主题样式
2. 确认项目里是否有全局样式覆盖文件，且没有被引用
3. 检查 CSS 变量名是否和源组件库一致，不一致需要重新映射
4. 确认是否有unexpected的全局样式冲突，比如* { box-sizing }或全局 button 样式影响组件

建议在迁移初期就把主题变量映射表建好，而不是等所有组件都迁移后再调样式。

6. 如何评估类似资源和工具的靠谱程度

6.1 看覆盖范围是“高频组件”还是“全组件”

如果要做组件库迁移，不是所有组件都需要同等关注。像Button、Input这类基础组件迁移容易，信息量大；像DatePicker、Table这种高复杂度组件才需要更细致的对照说明。

评估一个 Rosetta Stone 类资源时，先看它有没有覆盖高频高复杂度组件，再看它每个组件下是否拆到了 API 级。只有列出Button对应Button没有太大价值，能说明Button的类型、事件、样式、加载状态如何映射才有实际意义。

6.2 看版本是否锁定

组件库更新频繁，如果资源里只写组件名，不写版本，参考价值会大打折扣。一份好的资源会明确说明覆盖的是哪个版本区间，并在 API 变化时同步更新。

如果你找到的对照资源没有版本信息，可以参考思路，但一定要自己在 Demo 环境里验证一遍，不要直接照搬。

6.3 看是否有可运行示例

好的对照表往往配有代码示例，方便直接 copy。示例必须能运行，并且要有清晰的输入输出。比如按钮组件的示例，应该同时展示禁用、加载、不同尺寸、不同主题下的代码，而不是只展示基础用法。

如果一个资源只是文字描述，没有示例，那它只能作为线索，不能作为依据。实际落地前必须自己写代码验证。

6.4 看维护状态和社区反馈

可以关注三个点：最近更新时间、issue 讨论活跃度、是否有人提交过组件库新版本的补充。如果一个项目长期不更新，但另一个组件库已经大版本升级，那这个资源的准确性就要打问号。

可以把这份资源作为团队知识库的一部分，定期维护补充，而不是当作一次性参考。

7. 真正落地的几个建议

7.1 把对照表当作团队资产来维护

不要只在迁移时用一次。之后团队可能面临组件库升级、引入新组件、跨项目复用等场景，这些都可以通过不断扩充对照表来服务。

建议按月或按迭代维度维护，每次升级组件库时，把变化同步到对照表。长期来看，这张表的复用价值会超过最初迁移时的投入。

7.2 小团队可以先从“组件清单 + API 差异表”开始

不需要一开始就做成大型平台或自动化工具。我见过比较成功的团队，最开始就是一份 Markdown 或表格，里面记录高频组件的映射关系。等用到一定阶段，再逐步补充代码片段、示例工程和自动化校验脚本。

这个项目给我最大的启发是：与其背靠一堆组件库文档，不如建立一个能给团队形成共同语言的知识库，把“翻译”这件事集中管理起来。

7.3 不要指望零人工干预

如果你尝试过的自动迁移工具最终都没有完全跑通，不要意外。组件库之间的差异是多维度的，UI 层只是冰山一角，往上还有设计语言、交互习惯、无障碍支持，往下还有打包工具、样式隔离、主题系统。

所以效率最高的方式，其实是把人工投入花在“需要判断”的地方，让自动化脚本帮你完成改名、替换、简单映射这些重复劳动。而 Rosetta Stone 类资源的真正价值，正是帮你把“需要判断”的范围缩小到最小。

7.4 踩过几次坑后的最终结论

单任务先跑通，再谈批量。做组件库迁移也一样：先选一个页面做完整验证，再扩大范围。组件对照表不是一步到位的产品，而是边迁移边修正的动态资源。你越早开始建这张表，后面的组件库升级和项目重构就越省力。真正阻碍迁移效率的，往往不是代码量，而是两边组件库的语义差异没有被认真梳理过。