# 所有版本 · HeroUI > HeroUI v3 的所有更新与变更，包含新功能、修复以及破坏性变更。 - 页面: https://jiguang132.com/zh/systems/heroui/docs/releases - 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af > **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。 ## 最新版本 ### v3.2.2 **2026 年 6 月 19 日** 补丁版本：升级到 React Aria `1.19.0`（`react-aria@3.50.0`），为 `Tabs.ListContainer` 添加溢出滚动，修复清除/关闭按钮意外提交表单，以及 `Checkbox`、`Radio` 和 `Switch` 中视觉隐藏输入框导致的溢出滚动。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-2-2) --- ### v3.2.1 **2026 年 6 月 17 日** 补丁版本：`@heroui/react` 不再内置自己的 `react-aria` 副本。`react-aria` 的子路径在 Rollup 构建中被外部化，使消费方解析到项目中安装的单一 `react-aria`，而非内联副本。同时修复了 `SwitchGroup` 横向布局。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-2-1) --- ### v3.2.0 **2026 年 6 月 6 日** 基于 React Aria 1.18 的 Calendar 周/日视图、重做的年份选择器与范围日历演示，新增 Tooltip 延迟主题变量，并纳入随之发布的补丁修复。破坏性变更：`Radio`、`Checkbox`、`Switch` 改为显式的 `*.Content` 组合（控件嵌套进 `*.Content`，标签为纯文本、不嵌套 ``，帮助文本变为兄弟节点）。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-2-0) --- ### v3.1.0 **2026 年 5 月 25 日** 小版本发布：新增中文 React 文档与本地化示例，加入更可访问的 soft foreground 令牌和 vibrant palette 选项，统一滚动条系统，修复 `useTheme`、Toast、Fieldset、Link、浮层问题，并改进 Table、Picker 与 MenuItem 的 RTL 支持。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-1-0) --- ### v3.0.5 **2026 年 5 月 15 日** 补丁版本：`Text` 重命名为 `Typography` 以解决 `tailwind-merge` 冲突（⚠️ **破坏性变更**），派生颜色令牌重构为无前缀源变量，Checkbox 与 Radio 的 field-border 边框样式对齐，Calendar 悬停改用 `accent-soft-foreground` 以提升可读性，并新增 CLI 文档页。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-5) --- ### v3.0.4 **2026 年 5 月** 补丁版本：从 HeroUI Pro 移植的全新 `Text` 复合组件、文档主题选择器、在 45+ 个组件 CSS 文件中采用 `min()` 上限约束的圆角令牌、重做的 Table 聚焦环，以及对 Checkbox、Autocomplete、Tooltip 与表单字段内边距的修复。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-4) --- ### v3.0.3 **2026 年 4 月 17 日** 补丁版本：升级到 React Aria Components 1.17（合并依赖、安装更快、Table 支持可展开行），为 Vite 与 CRA 提供 `useTheme` Hook，为轻量级组件提供 DOM 多态的 render prop，并修复了 NumberField 的重置问题以及嵌套 Tabs 的样式问题。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-3) --- ### v3.0.2 **2026 年 4 月 3 日** 修复了多个 bug，Drawer 过渡更加平滑，新增了 `--backdrop` 主题变量，并优化了 trigger、arrow 与 Tag 的样式。修复了 Autocomplete 弹出层的宽度跟踪问题，浮层触发器现在使用 `inline-block`，Tag 在间距与无障碍方面也有所改进。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-2) ### v3.0.0 **2026 年 3 月** 面向 React 与 React Native 的彻底重写。包含 75+ Web 组件、37 个原生组件、Tailwind CSS v4、React Aria、复合组件架构、基于 OKLCH token 的 CSS 优先主题、通过 `data-reduce-motion` 控制动画，并面向利用 MCP Server、Agent Skills 与 LLMs.txt 的 AI 辅助开发而打造。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0) --- ### HeroUI Pro 面向 React 与 React Native 的高级组件、模板与 AI 工具。预售价格现已上线。 [访问 heroui.pro 查看套餐与定价 →](https://heroui.pro) --- ### v3.0.0-rc.1 **2026 年 3 月 14 日** 新增七个组件（[Drawer](/systems/heroui/docs/components/drawer)、[ToggleButton](/systems/heroui/docs/components/toggle-button)、[ToggleButtonGroup](/systems/heroui/docs/components/toggle-button-group)、[Meter](/systems/heroui/docs/components/meter)、[ProgressBar](/systems/heroui/docs/components/progress-bar)、[ProgressCircle](/systems/heroui/docs/components/progress-circle)、[Toolbar](/systems/heroui/docs/components/toolbar)），为 [Table](/systems/heroui/docs/components/table) 和 [ListBox](/systems/heroui/docs/components/list-box) 引入了 **虚拟化**，[ButtonGroup](/systems/heroui/docs/components/button-group) 新增 `ButtonGroup.Separator` 与垂直方向支持，React Aria Components 升级到 v1.16.0。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-rc-1) --- ### v3.0.0-beta.8 **2026 年 3 月 2 日** 此版本新增三个组件（[Badge](/systems/heroui/docs/components/badge)、[Pagination](/systems/heroui/docs/components/pagination)、[Table](/systems/heroui/docs/components/table)），并为 [DateField](/systems/heroui/docs/components/date-field) 与 [TimeField](/systems/heroui/docs/components/time-field) 提供了新的 `InputContainer` 组合 API。⚠️ **破坏性变更**：TextField 的 CSS 类已从 `.text-field` 重命名为 `.textfield`。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-beta-8) --- ### v3.0.0-beta.7 **2026 年 2 月 18 日** 此版本引入了完整的**日期与时间**系统，包含四个新组件（[Calendar](/systems/heroui/docs/components/calendar)、[RangeCalendar](/systems/heroui/docs/components/range-calendar)、[DatePicker](/systems/heroui/docs/components/date-picker)、[DateRangePicker](/systems/heroui/docs/components/date-range-picker)），新增了 [Switch.Content](/systems/heroui/docs/components/switch) 子组件、显式的 [Tabs.Separator](/systems/heroui/docs/components/tabs) 用于按需启用分隔线，以及 ⚠️ **破坏性变更**：从 Tabs 中移除 `hideSeparator`，并将 `DateInputGroup` / `ColorInputGroup` 合并到各自的 Field 组件之下。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-beta-7) --- ### v3.0.0-beta.6 **2026 年 2 月 6 日** 此版本引入了完整的**颜色系统**，包含六个新组件（[ColorPicker](/systems/heroui/docs/components/color-picker)、[ColorArea](/systems/heroui/docs/components/color-area)、[ColorSlider](/systems/heroui/docs/components/color-slider)、[ColorField](/systems/heroui/docs/components/color-field)、[ColorSwatch](/systems/heroui/docs/components/color-swatch)、[ColorSwatchPicker](/systems/heroui/docs/components/color-swatch-picker)），对 [Toast](/systems/heroui/docs/components/toast) 进行了重大改进，加入了加载状态与 Promise 支持，[Separator](/systems/heroui/docs/components/separator) 新增变体，以及 ⚠️ **破坏性变更**：将 `Toast.Container` 重命名为 `Toast.Provider`，并将 CSS 类名统一为连字符格式。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-beta-6) --- ### v3.0.0-beta.5 - 修复构建问题 ### v3.0.0-beta.4 **2026 年 1 月 20 日** > **已修复关键构建问题**：此版本（beta.4）存在一个关键构建问题，已在 **beta.5** 中修复。请升级到 `@heroui/styles@3.0.0-beta.5` 与 `@heroui/react@3.0.0-beta.5`，以确保 TypeScript 声明文件能正确生成、导出能正确解析。 此版本引入了用于可视化主题定制的全新[主题构建器](https://heroui.com/themes)、三个新组件（[Autocomplete](/systems/heroui/docs/components/autocomplete)、[Breadcrumbs](/systems/heroui/docs/components/breadcrumbs)、[Toast](/systems/heroui/docs/components/toast)），为 [Tabs](/systems/heroui/docs/components/tabs) 添加了 secondary 变体，为 [Input](/systems/heroui/docs/components/input) 与 [InputGroup](/systems/heroui/docs/components/input-group) 添加了 primary / secondary 变体，以及 ⚠️ **破坏性变更**：移除了 Link 的下划线变体，并从表单组件中移除了 `isInSurface` prop。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-beta-4) --- ### v3.0.0-beta.3 **2025 年 12 月 19 日** 此版本引入了七个新组件（[ButtonGroup](/systems/heroui/docs/components/button-group)、[DateField](/systems/heroui/docs/components/date-field)、[ErrorMessage](/systems/heroui/docs/components/error-message)、[ScrollShadow](/systems/heroui/docs/components/scroll-shadow)、[SearchField](/systems/heroui/docs/components/search-field)、[TagGroup](/systems/heroui/docs/components/tag-group)、[TimeField](/systems/heroui/docs/components/time-field)），为表单与输入组件添加了 `fullWidth` 支持，为 [Tabs](/systems/heroui/docs/components/tabs)、[ButtonGroup](/systems/heroui/docs/components/button-group) 和 [Accordion](/systems/heroui/docs/components/accordion) 引入 `hideSeparator` 以获得更简洁的布局，包含若干样式修复，以及 ⚠️ **破坏性变更**：移除 `asChild` prop，并更新了 [AlertDialog](/systems/heroui/docs/components/alert-dialog) 与 [Modal](/systems/heroui/docs/components/modal) 的 backdrop 变体。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-beta-3) --- ### v3.0.0-beta.2 **2025 年 11 月 20 日** 此版本引入了六个重要的新组件（[AlertDialog](/systems/heroui/docs/components/alert-dialog)、[ComboBox](/systems/heroui/docs/components/combo-box)、[Dropdown](/systems/heroui/docs/components/dropdown)、[InputGroup](/systems/heroui/docs/components/input-group)、[Modal](/systems/heroui/docs/components/modal)、[NumberField](/systems/heroui/docs/components/number-field)），增强了主题兼容性与动效偏好支持，改进了 [Select](/systems/heroui/docs/components/select) 组件的 API（包含 ⚠️ **破坏性变更**），并附带多项优化和 bug 修复。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-beta-2) --- ### v3.0.0-beta.1 **2025 年 11 月 6 日** 此版本对 HeroUI v3 进行了全面重新设计，将 v2 的美观与动效与 v3 的简洁性融为一体。所有组件均经过重新设计，新增 8 个组件（[Alert](/systems/heroui/docs/components/alert)、[Checkbox](/systems/heroui/docs/components/checkbox)、[InputOTP](/systems/heroui/docs/components/input-otp)、[ListBox](/systems/heroui/docs/components/list-box)、[Select](/systems/heroui/docs/components/select)、[Slider](/systems/heroui/docs/components/slider)、[Surface](/systems/heroui/docs/components/surface)），并对设计系统进行了彻底重构，包括更完善的颜色 token、阴影体系与整体架构。本版本还包含对设计系统变量、组件 API 以及灵活组件模式的破坏性变更。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-beta-1) --- ## 早期版本 ### v3.0.0-alpha.35 **2025 年 10 月 21 日** #### React Server Components 支持 - 修复了复合组件在 React Server Components（RSC）中无法正常工作的关键问题 - 将复合组件模式的逻辑从组件移至 index 文件，解决 `"use client"` 冲突 - **（⚠️ 破坏性变更）**：主组件现在需要 `.Root` 后缀（例如 `` → ``） - 命名导出保持不变，并完全继续支持 #### React 19 相关改进 - 移除了 `forwardRef`（[React 19](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop) 现已原生支持） - 简化了 Context 的使用方式（`Context.Provider` → [React 19](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider)） #### Switch 组件重构 - **（⚠️ 破坏性变更）**：将 Switch 与 SwitchGroup 拆分为独立组件 - 更简洁的 API：`` 取代 `` 和 `` - 与 Radio / RadioGroup 模式保持一致 - 各自拥有独立的样式、类型和实现 #### 受影响的组件 以下复合组件均需要使用 `.Root` 后缀：`Accordion`、`Avatar`、`Card`、`Disclosure`、`Fieldset`、`Kbd`、`Link`、`Popover`、`Radio`、`Switch`、`Tabs`、`Tooltip` [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-alpha-35) ### v3.0.0-alpha.34 **2025 年 10 月 15 日** - 新增基于表单的组件：[Description](/systems/heroui/docs/components/description)、[FieldError](/systems/heroui/docs/components/field-error)、[Fieldset](/systems/heroui/docs/components/fieldset)、[Form](/systems/heroui/docs/components/form)、[Input](/systems/heroui/docs/components/input)、[Label](/systems/heroui/docs/components/label)、[RadioGroup](/systems/heroui/docs/components/radio-group)、[TextField](/systems/heroui/docs/components/text-field) 以及 [TextArea](/systems/heroui/docs/components/textarea) - 引入表单字段相关的 token `--field-*` - 按类别重新组织 Storybook - **（破坏性变更）**：在 [Skeleton](/systems/heroui/docs/components/skeleton) 中将 `--skeleton-default-animation-type` 重命名为 `--skeleton-animation` - 统一了各组件中 `data-slot` 标记的命名 - 改进了文档 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-alpha-34) ### v3.0.0-alpha.33 **2025 年 10 月 5 日** - 将 RAC 升级至 [2025 年 10 月 2 日发布的版本](https://react-spectrum.adobe.com/releases/2025-10-02.html) - 调整了 [Tabs](/systems/heroui/docs/components/tabs) 中 Indicator 的顺序（**破坏性变更**） - 将 [Tabs](/systems/heroui/docs/components/tabs) 组件改为使用 React Aria 的 `SelectionIndicator`，现已支持 SSR - 更新了 [Disclosure](/systems/heroui/docs/components/disclosure) 和 [Disclosure Group](/systems/heroui/docs/components/disclosure-group) 组件，使其在展开/折叠动画中使用 RAC 的 CSS 变量 - 更新了 [Switch](/systems/heroui/docs/components/switch) 组件的样式与动画 - 为 [Switch](/systems/heroui/docs/components/switch#sizes) 新增 `size` 变体并补充了对应演示 - 在 [Button](/systems/heroui/docs/components/button)、[Tabs](/systems/heroui/docs/components/tabs)、[Disclosure](/systems/heroui/docs/components/disclosure)、[Disclosure Group](/systems/heroui/docs/components/disclosure-group) 中添加了相关示例 - 改进了文档 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-alpha-33) ### v3.0.0-alpha.32 **2025 年 10 月 1 日** 重新设计了 Card 组件，引入了[新变体](/systems/heroui/docs/components/card)，新增了 [CloseButton](/systems/heroui/docs/components/close-button) 组件，发布了面向 AI 编码助手的 [MCP 服务器](/docs/ui-for-agents/mcp-server)，并改进了文档。 [阅读完整发布说明 →](/systems/heroui/docs/releases/v3-0-0-alpha-32) ### v3.0.0-alpha.31 **2025 年 9 月 22 日** - 🎨 **展示页面** - 使用 HeroUI 构建的站点案例集 - 🌀 **DisclosureGroup 组件** - 将多个 Disclosure 组合在一起 - 📇 **Card 组件**（预览） - Card 组件的首个版本 - 🔀 **Switch 组件**（预览） - 用于设置项的切换开关 --- ## 发布周期 HeroUI v3 现已稳定。后续版本将遵循固定的发布周期： - **补丁版本**：按需修复 bug 与小幅优化 - **次要版本**：新增组件与功能，通常每月一次 - **主版本**：包含架构层面的变更，并提供迁移指南 ## 参与贡献 发现问题或希望参与贡献？欢迎查看我们的 [GitHub 仓库](https://github.com/heroui-inc/heroui)。 --- JGuang 全部资源索引: https://jiguang132.com/llms.txt