# v3.0.0-rc.1 · HeroUI > 新增 7 个组件（Drawer、ToggleButton、ToggleButtonGroup、Meter、ProgressBar、ProgressCircle、Toolbar），Table 与 ListBox 支持虚拟化，ButtonGroup 多项改进，以及若干 bug 修复。 - 页面: https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 - 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af 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 与 ListBox 支持虚拟化，ButtonGroup 新增 `Separator` 子组件并支持垂直方向，React Aria Components 升级到 v1.16.0。 ## 安装 升级到最新版本： #### npm ```bash npm i @heroui/styles@rc @heroui/react@rc ``` #### pnpm ```bash pnpm add @heroui/styles@rc @heroui/react@rc ``` #### yarn ```bash yarn add @heroui/styles@rc @heroui/react@rc ``` #### bun ```bash bun add @heroui/styles@rc @heroui/react@rc ``` > **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。 ## 新增功能 ### 新组件 - **[Drawer](#drawer)**：滑出式面板，支持拖拽关闭、4 种放置位置、多种背景遮罩变体以及可滚动的内容区（[文档](/systems/heroui/docs/components/drawer)） - **[ToggleButton](#toggle-button)**：选中 / 未选中两态的切换按钮，支持全部按钮变体以及仅图标模式（[文档](/systems/heroui/docs/components/toggle-button)） - **[ToggleButtonGroup](#toggle-button-group)**：单选或多选的切换按钮组，支持 attached / detached 布局以及方向设置（[文档](/systems/heroui/docs/components/toggle-button-group)） - **[Meter](#meter)**：在已知范围内呈现某个数值——例如磁盘占用、密码强度、配额等（[文档](/systems/heroui/docs/components/meter)） - **[ProgressBar](#progress-bar)**：线性进度条，支持确定 / 不确定态、多种颜色与自定义格式（[文档](/systems/heroui/docs/components/progress-bar)） - **[ProgressCircle](#progress-circle)**：基于 SVG 的环形进度条，可自定义轨道圆与填充圆（[文档](/systems/heroui/docs/components/progress-circle)） - **[Toolbar](#toolbar)**：将按钮、切换控件与分隔线按水平或垂直方向组合在一起的工具栏组件（[文档](/systems/heroui/docs/components/toolbar)） ### Drawer 带有背景遮罩的滑出式浮层面板，支持顶部 / 底部 / 左侧 / 右侧四种放置位置、拖拽关闭手势以及多种背景遮罩变体。复合部件包括：`Trigger`、`Backdrop`、`Content`、`Dialog`、`Header`、`Heading`、`Body`、`Footer`、`Handle`、`CloseTrigger`。 > 示例 `drawer-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **放置位置：** > 示例 `drawer-placements`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **配合表单使用：** > 示例 `drawer-with-form`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### Toggle Button 具备状态的切换按钮，可在选中与未选中之间切换。支持全部按钮变体与尺寸、仅图标模式，以及受控 / 非受控两种使用方式。 > 示例 `toggle-button-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **变体：** > 示例 `toggle-button-variants`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### Toggle Button Group 单选或多选的切换按钮组。支持 attached（连接式）与 detached（分离式）两种布局、垂直方向、整宽展示，以及一个 `Separator` 子组件。 > 示例 `toggle-button-group-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **选择模式：** > 示例 `toggle-button-group-selection-mode`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **Attached 模式：** > 示例 `toggle-button-group-attached`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### Meter 在已知范围内呈现某个数值——例如磁盘占用、密码强度、配额等。复合部件包括：`Root`、`Output`、`Track`、`Fill`。 > 示例 `meter-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **颜色：** > 示例 `meter-colors`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### Progress Bar 线性进度指示器，支持确定 / 不确定态、颜色变体、多种尺寸以及自定义数值显示。复合部件包括：`Root`、`Output`、`Track`、`Fill`。 > 示例 `progress-bar-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **不确定态：** > 示例 `progress-bar-indeterminate`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### Progress Circle 基于 SVG 的环形进度条，提供 `TrackCircle` 与 `FillCircle` 两个子组件，便于直接控制 SVG。同时支持确定与不确定态。 > 示例 `progress-circle-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **自定义 SVG：** > 示例 `progress-circle-custom-svg`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### Toolbar 将按钮、切换按钮与分隔线组合到一个具备无障碍语义的工具栏中。支持水平或垂直方向，可与 `ButtonGroup` 和 `ToggleButtonGroup` 组合使用。 > 示例 `toolbar-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 **配合 Button Group 使用：** > 示例 `toolbar-with-button-group`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ## 组件改进 ### ButtonGroup 的增强 新增的 `ButtonGroup.Separator` 子组件可在按钮之间显式插入一条视觉分隔线。在水平和垂直两种方向下都能正常工作。 > 示例 `button-group-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### Table 与 ListBox 的虚拟化 Table 与 ListBox 现在可以借助 React Aria 的 `Virtualizer` 来支持大数据集的虚拟化渲染。`Virtualizer`、`TableLayout` 和 `ListLayout` 都已从 `@heroui/react` 重新导出。 > 示例 `table-virtualization`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### ButtonGroup 的方向 `ButtonGroup` 现在接受一个 `orientation` prop（`"horizontal"` | `"vertical"`），并在两种方向下都正确处理边框圆角与分隔线方向。根元素也已从 `` 升级为 React Aria 的 `Group`，从而具备正确的 `role="group"` 语义。 > 示例 `button-group-orientation`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/releases/v3-0-0-rc-1 ### ButtonGroup 的焦点环 成组按钮上的焦点环现在使用 `ring-inset`，确保焦点环留在按钮内部边界，而不会与相邻按钮重叠。 ### 细粒度的组件引入 `@heroui/react` 现在支持按组件的子路径入口，方便更明确地按需引入（[#6301](https://github.com/heroui-inc/heroui/pull/6301)）： ```tsx // Before — root entrypoint import { Button } from "@heroui/react"; // After — granular subpath import import { Button } from "@heroui/react/button"; ``` ## 依赖更新 将 `react-aria-components` 从 v1.15.1 升级到 v1.16.0，同时升级了相关包： | 包名 | 旧版本 | 新版本 | |------|--------|--------| | `react-aria-components` | 1.15.1 | 1.16.0 | | `@react-aria/i18n` | 3.12.15 | 3.12.16 | | `@react-aria/utils` | 3.33.0 | 3.33.1 | | `@react-types/shared` | 3.33.0 | 3.33.1 | | `@react-types/color` | 3.1.3 | 3.1.4 | | `@internationalized/date` | 3.11.0 | 3.12.0 | | `@react-stately/data` | 3.15.1 | 3.15.2 | ## Bug 修复 - **InputGroup**：聚焦样式现在仅在实际的 input / textarea 获得焦点时（`:has([data-slot]:focus)`）才会触发，不再因 `:focus-within` 而被任意可聚焦的子元素触发（[#6274](https://github.com/heroui-inc/heroui/pull/6274)） - **Avatar**：fallback 元素现在会从父级继承 `border-radius`，而不再硬编码为 `rounded-full`，因此 `className` 覆盖能够正确生效（[#6300](https://github.com/heroui-inc/heroui/pull/6300)） - **Modal 与 AlertDialog**：背景遮罩的点击事件不会再透过 portal 传播到父级元素（[#6297](https://github.com/heroui-inc/heroui/pull/6297)） - **Table**：修复了 Firefox 中表头圆角与背景色溢出的问题（[#6298](https://github.com/heroui-inc/heroui/pull/6298)） ## 链接 - [组件文档](/systems/heroui/docs/components) - [Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) - [GitHub 仓库](https://github.com/heroui-inc/heroui) - [GitHub PR #6285](https://github.com/heroui-inc/heroui/pull/6285) ## 贡献者 感谢每一位为本次发布做出贡献的开发者！ --- JGuang 全部资源索引: https://jiguang132.com/llms.txt