version-migration

技能：IDS 版本迁移

适用场景

• 从 IDS v5（或 v4）迁移到 IDS v6
• 从 OUI（@iress/oui）迁移到 IDS v6
• 将导入路径从 @iress/components-react 更新为 @iress-oss/ids-components
• 通过 IressForm/IressFormField 将 Formik 表单转换为 React Hook Form
• 更新使用 IDS v4 测试工具的测试文件
• 审查迁移 PR，确保其正确性

决策表：选择哪种迁移路径？

当前技术栈	迁移路径	复杂度	参考
仅 OUI	OUI→v6 指南	高（表单架构变更）	prop-renames.md
仅 IDS v4	v4→v6 指南	中（表单架构变更）	prop-renames.md
仅 IDS v5	v5→v6 指南	低至中	v5-to-v6-migration.md
OUI + IDS v4	OUI→v6 和 v4→v6 指南	高（表单架构变更）	prop-renames.md
OUI + IDS v5	OUI→v6 指南 + IDS 变更的 v5→v6 指南	高（表单架构变更）	v5-to-v6-migration.md

Storybook 中提供了带差异查看器的完整交互式指南：

• v4→v5 指南
• v5→v6 指南
• OUI→v6 指南

---

迁移前评估

开始迁移前，请运行以下脚本（或手动执行检查）：

1. 识别当前版本：scripts/detect-version.sh — 检测 IDS/OUI 版本并推荐迁移路径
2. 审查组件用法：scripts/audit-components.sh — 生成组件用法报告
3. 检查已弃用的属性：scripts/find-deprecated-props.sh — 查找会导致问题的属性
4. 检查表单架构：scripts/find-formik.sh — 找出需要迁移的 Formik 表单
5. 检查测试模式：scripts/find-test-utils.sh — 查找旧的测试工具
6. 检查自定义 CSS：搜索可能导致问题的 .oui-、.ids- 或 iress- 类选择器
7. 设置 VRT（推荐）：scripts/setup-playwright-vrt.sh — 生成 Playwright 视觉回归测试
8. 捕获基准截图：迁移前运行 VRT 测试套件，捕获当前状态
9. 创建迁移分支：确保在需要时可以回滚

---

快速参考：包变更

导入路径

// ❌ Old (IDS v4)
import { IressButton } from '@iress/components-react';

// ❌ Old (OUI)
import { Button, Input } from '@iress/oui';

// ✅ IDS v6 (install with @beta tag: npm install @iress-oss/ids-components@beta)
import { IressButton, IressInput } from '@iress-oss/ids-components';

重要： IDS v6 目前处于 beta 阶段。请使用 @beta 标签安装：

npm install @iress-oss/ids-components@beta
npm install @iress-oss/ids-tokens@beta  # if using tokens directly

CSS 入口点

// ✅ Required in your app entry point
import '@iress-oss/ids-components/dist/style.css';

Token 包

// ✅ Required for design tokens
import '@iress-oss/ids-tokens/build/css-vars.css';
import { cssVars } from '@iress-oss/ids-tokens';

---

主要迁移事项

v5 → v6 迁移

如需了解从 IDS v5 迁移到 v6 的具体步骤，请参阅 references/v5-to-v6-migration.md，内容包括：

• 包和 CSS 导入变更
• 组件重命名（IressBadge → IressPill、IressFilter → IressDropdownMenu 等）
• 各组件的属性变更（Button、Alert、Toggle、Field、Modal、Select）
• 图标迁移（FontAwesome → Material Symbols）
• 表单迁移模式

组件重命名

不同版本间更改名称的组件（IDS 和 OUI → v6），以及已移除和新增的组件。完整映射请参见 references/component-renames.md。

主要重命名：IressBadge → IressPill、IressRichSelect → IressSelect、IressField → IressFormField、IressFilter → IressDropdownMenu。

Prop 重命名（关键 — 已对照源代码验证）

使用旧的 prop 名称会静默失效。完整列表请参见 references/prop-renames.md。

最常见的重命名：

组件	旧 prop（OUI）	新 prop（v6）
Alert	context	status
Modal	onHide	onShowChange
Fieldset/RadioGroup	legend	label
Label	optional	required

组件（IDS v4/v5）	旧 prop	新 prop（v6）
IressButton	variant	mode
IressAlert	variant	status
IressModal	isOpen	show
IressModal	onClose	onShowChange
IressModal	title	heading
IressPanel	background	bg
IressStack/IressInline	gutter	gap

表单迁移（Formik → React Hook Form）

这是最重要的架构变更。表单使用带有 render prop 的 IressForm + IressFormField，取代 Formik 的 <Field as={...}> 模式。Yup schema 改为逐字段设置 rules prop。

验证映射、迁移前后示例及常见模式请参见 references/form-migration.md。

快速示例：

<IressForm defaultValues={{ email: '' }} onSubmit={handle}>
  <IressFormField
    name="email"
    label="Email"
    render={(props) => <IressInput {...props} type="email" />}
    rules={{ required: 'Required' }}
  />
  <IressButton type="submit" mode="primary">
    Submit
  </IressButton>
</IressForm>

测试迁移

IDS v6 使用标准的 React Testing Library — 无需特殊测试工具。将 idsFireEvent 替换为 fireEvent/userEvent，移除 mockLazyLoadedComponents，优先使用 getByRole/getByLabelText，而非 getByTestId。

导入项变更、模式映射、配置更新和表单测试示例请参见 references/testing-migration.md。

样式迁移

OUI CSS 类和 IDS v4 Stencil 类已移除。请使用样式 props（p、m、bg、gap、scrollable）或设计令牌（var(--iress-*)）。如果自定义 CSS 被覆盖，请声明 @layer 顺序。

示例和 AG Grid 迁移请参见 references/styling-migration.md。

---

迁移后验证

完成迁移后，运行 scripts/validate-migration.sh 或手动验证：

1. 自动化检查：运行验证脚本，检查常见问题
2. 视觉回归：运行 VRT 测试套件并检查所有视觉差异（参见 references/visual-regression-testing.md）
3. 视觉检查：所有组件均可渲染，且控制台没有错误或警告
4. 表单功能：提交表单并验证校验规则是否正常工作
5. 测试套件：使用新的测试模式后所有测试均通过（没有 idsFireEvent 等）
6. 无障碍：键盘导航和屏幕阅读器功能保持正常
7. 样式：没有样式缺失，并检查响应式断点
8. 交互状态：悬停、聚焦、禁用和加载状态均按预期工作
9. 构建：生产构建顺利完成且没有错误，并检查包大小

验证脚本会检查：

• 旧导入（@iress/oui、@iress/components-react）
• 旧测试工具（idsFireEvent、mockLazyLoadedComponents）
• 已弃用的 props（variant=、isOpen=、gutter= 等）
• 必需的 CSS 导入
• 是否仍在使用 Formik

---

常见注意事项

请参阅 references/common-gotchas.md，获取全面的故障排查指南，内容涵盖：

• 关键的破坏性变更（缺少 CSS、验证、重命名的属性）
• IDS v4 React → v6 React 的注意事项（测试工具、插槽、辅助工具、图标）
• OUI 特有的注意事项（属性重命名、已移除的组件）
• 组件 API 变更（表单字段、样式、组合模式）
• 表单架构变更（Formik → React Hook Form）

---

交叉引用

生成的迁移指南（请阅读以了解完整详情）

• v4→v5 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-v5.md
• v5→v6 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-v6.md
• OUI→v6 — node_modules/@iress-oss/ids-components/.ai/guides/migration-guides-oui.md

组件和模式文档

• 组件文档 — node_modules/@iress-oss/ids-components/.ai/components/
• 模式文档 — node_modules/@iress-oss/ids-components/.ai/patterns/
• 索引 — node_modules/@iress-oss/ids-components/.ai/index.json

相关技能

• token-usage — 设计令牌使用模式
• ui-translation — 从头开始构建新的 IDS v6 UI
• ui-doctor — 审核 IDS 合规性

参考资料

• Storybook 和指南： https://main--691abcc79dfa560a36d0a74f.chromatic.com