迁移

面向 AI 助手

以下是 AI 助手获取迁移文档的三种方式。我们推荐使用 HeroUI Migration MCP 服务器，并充分利用其 prompt 与工具，不过其它方式也都能为 agent 提供完整的文档。

主要变化

• 依赖项：将 React 升级到 v19+、HeroUI 包升级到 v3、Tailwind CSS 升级到 v4，并移除 Framer Motion
• 无需 Provider：v3 不再需要 HeroUIProvider
• 组件 API 更新：许多组件改用 React Aria Components 模式
• 复合组件：全新的复合组件模式带来了更好的定制能力。详情请参阅各组件的迁移指南。
• 已移除的 Hooks：v2 中的组件 Hooks（如 useSwitch、useInput）已被移除——请改用复合组件。useDisclosure 已被替换为 useOverlayState。详情请参阅 Hooks 迁移指南。
• 配置变更：从 Tailwind 配置中移除 heroui() 插件，更新 CSS 导入，并删除 hero.ts 文件
• 条目标识：集合类组件（Dropdown、ListBox、Select、Accordion 等）在 v3 中改用 id 和 textValue；列表本身仍需保留 React 的 key。

条目标识与无障碍（key、id、textValue）

在 v2 中，集合类组件（Dropdown、ListBox、Select、Accordion 等）使用 React 的 key 作为条目标识。同一个值既驱动 React 的列表协调，又承担组件的选中/展开状态。在使用 React Aria Components 的 v3 中，这两种职责被拆分开：

• id — v3 在每个条目上使用显式的 id 属性来表示选中状态、焦点以及回调（例如 selectedKeys、expandedKeys、onSelectionChange）。请使用与你在 v2 中给 key 设置的相同（或等效）的值，这样状态和回调仍能正确指向对应的条目。
• textValue — 当条目的可见内容不是纯文本时（例如使用了 Label、图标或 Description），v3 需要在条目上提供 textValue。它用于屏幕阅读器播报和键入快速定位（type-ahead）。
• key — 继续在列表项上使用 React 的 key。它仍然是 React 列表协调所必需的，且与 id 相互独立。

迁移时：为 v3 的 API 添加 id（必要时再加上 textValue），同时保留供 React 使用的 key。

迁移策略

如果不做特殊设置，HeroUI v2 与 v3 不能在同一个项目中共存。你可以选择以下两种迁移方式：

一次性完整迁移

适用场景： 能够集中投入时间、一次性完成迁移的项目。

工作方式：

• 先迁移所有组件代码（此阶段项目将无法正常运行）
• 将依赖项切换到 v3
• 完成样式迁移

优点：

• 配置更简单——无需复杂的共存配置
• 切换更干净——同一时间只有一个版本处于激活状态
• 由 Migration MCP 的 prompt 提供支持

缺点：

• 项目在迁移期间无法正常运行
• 必须在切换依赖之前完成所有组件的迁移

开始迁移： 完整迁移指南

渐进式迁移

适用场景： 需要在迁移过程中保持可用的项目、希望分阶段逐步迁移的团队，以及按功能逐个迁移的大型代码库。

工作方式：

• 通过 pnpm 别名或组件包来设置共存
• 在保持项目可用的前提下，逐个迁移组件
• 完成迁移后再移除 v2 依赖项

优点：

• 项目在迁移期间始终可用
• 可以分阶段、按需逐步推进
• 可以将 v3 组件与 v2 并存测试

缺点：

• 初始配置更为复杂
• 可能出现样式冲突
• 需要同时管理两个版本

开始迁移： 渐进式迁移指南

组件迁移参考

可以通过下表快速查找每个组件的迁移指南。点击「迁移指南」列中的链接，即可跳转到对应的详细迁移说明。

组件开发状态：标有 🔄 进行中或 📋 计划中的组件仍在开发中。可以查看路线图了解任务状态。这些组件的迁移指南将在开发完成后提供。

v2 组件	v3 组件	状态	迁移指南
Accordion	Accordion	✅ 可用	查看指南 →
Alert	Alert	✅ 可用	查看指南 →
Autocomplete	ComboBox	✅ 已重命名	查看指南 →
Avatar	Avatar	✅ 可用	查看指南 →
Badge	Badge	✅ 可用	查看指南 →
Breadcrumbs	Breadcrumbs	✅ 可用	查看指南 →
Button	Button	✅ 可用	查看指南 →
ButtonGroup	ButtonGroup	✅ 可用	查看指南 →
Calendar	Calendar	✅ 可用	查看指南 →
Card	Card	✅ 可用	查看指南 →
Checkbox	Checkbox	✅ 可用	查看指南 →
CheckboxGroup	CheckboxGroup	✅ 可用	查看指南 →
Chip	Chip	✅ 可用	查看指南 →
Code	❌	❌ 已移除	查看指南 →
DateInput	DateField	✅ 已重命名	查看指南 →
DatePicker	DatePicker	✅ 可用	查看指南 →
DateRangePicker	DateRangePicker	✅ 可用	查看指南 →
TimeInput	TimeField	✅ 已重命名	查看指南 →
Divider	Separator	✅ 已重命名	查看指南 →
Drawer	Drawer	✅ 可用	查看指南 →
Dropdown	Dropdown	✅ 可用	查看指南 →
Form	Form	✅ 可用	查看指南 →
Image	❌	❌ 已移除	查看指南 →
Input	TextField、Input、InputGroup	✅ 可用	查看指南 →
InputOTP	InputOTP	✅ 可用	查看指南 →
Kbd	Kbd	✅ 可用	查看指南 →
Link	Link	✅ 可用	查看指南 →
Listbox	ListBox	✅ 可用	查看指南 →
Modal	Modal	✅ 可用	查看指南 →
Navbar	❌	❌ 已移除	查看指南 →
NumberInput	NumberField	✅ 已重命名	查看指南 →
Pagination	Pagination	✅ 可用	查看指南 →
Popover	Popover	✅ 可用	查看指南 →
Progress	ProgressBar	✅ 已重命名	查看指南 →
CircularProgress	ProgressCircle	✅ 已重命名	查看指南 →
Radio	Radio	✅ 可用	查看指南 →
RadioGroup	RadioGroup	✅ 可用	查看指南 →
RangeCalendar	RangeCalendar	✅ 可用	查看指南 →
Ripple	❌	❌ 已移除	参见 Button 的水波纹效果 →
ScrollShadow	ScrollShadow	✅ 可用	查看指南 →
Select	Select	✅ 可用	查看指南 →
Skeleton	Skeleton	✅ 可用	查看指南 →
Slider	Slider	✅ 可用	查看指南 →
Snippet	❌	❌ 已移除	查看指南 →
Spacer	❌	❌ 已移除	查看指南 →
Spinner	Spinner	✅ 可用	查看指南 →
Switch	Switch	✅ 可用	查看指南 →
Table	Table	✅ 可用	查看指南 →
Tabs	Tabs	✅ 可用	查看指南 →
Toast	Toast	✅ 可用	查看指南 →
Tooltip	Tooltip	✅ 可用	查看指南 →
User	❌	❌ 已移除	查看指南 →

v3 中新增的组件

v3 引入了一系列 v2 中尚未提供的全新组件：

组件	用途	文档
TextField	增强型文本输入框，支持 label 与 description	查看文档 →
TextArea	多行文本输入组件	查看文档 →
AlertDialog	用于确认与提醒的模态对话框	查看文档 →
Label	无障碍的表单标签组件	查看文档 →
Description	表单字段的辅助说明文本	查看文档 →
FieldError	表单字段的错误信息显示	查看文档 →
Fieldset	对相关表单字段进行分组	查看文档 →
InputGroup	将多个输入框组合在一起	查看文档 →
Surface	带有层级样式的容器组件	查看文档 →
Disclosure	可展开 / 可折叠的内容区域	查看文档 →
DisclosureGroup	用于管理多个 Disclosure 区域的复合组件	查看文档 →
SearchField	带清除按钮与可选加载状态的搜索输入框	查看文档 →
DateField	配合日历选择器的日期输入框	查看文档 →
TimeField	时间输入组件	查看文档 →
Tag、TagGroup	用于选择或展示的 Tag 与 TagGroup	查看文档 →
ColorPicker	颜色选择（ColorArea、ColorField、ColorSlider、ColorSwatch、ColorSwatchPicker）	查看文档 →
CloseButton	用于关闭或解除浮层的触发按钮	查看文档 →
ErrorMessage	表单字段错误信息展示（基于 React Aria 集成）	查看文档 →

其他迁移指南

• Hooks 迁移指南：将 Hooks 从 v2 迁移到 v3 的详细说明
• 样式迁移指南：更新工具类、颜色 token 与组件样式的综合指南

获取帮助

如果你在迁移过程中遇到问题：

1. 查看 v3 文档
2. 查阅具体组件的迁移指南
3. 在 GitHub Discussions 中查找或提问
4. 加入 Discord 社区