v3.0.0-rc.1

新增七个组件：Drawer、ToggleButton、ToggleButtonGroup、Meter、ProgressBar、ProgressCircle 与 Toolbar。Table 与 ListBox 支持虚拟化，ButtonGroup 新增 Separator 子组件并支持垂直方向，React Aria Components 升级到 v1.16.0。

安装

升级到最新版本：

npm i @heroui/styles@rc @heroui/react@rc

pnpm add @heroui/styles@rc @heroui/react@rc

yarn add @heroui/styles@rc @heroui/react@rc

bun add @heroui/styles@rc @heroui/react@rc

新增功能

新组件

• Drawer：滑出式面板，支持拖拽关闭、4 种放置位置、多种背景遮罩变体以及可滚动的内容区（文档）
• ToggleButton：选中 / 未选中两态的切换按钮，支持全部按钮变体以及仅图标模式（文档）
• ToggleButtonGroup：单选或多选的切换按钮组，支持 attached / detached 布局以及方向设置（文档）
• Meter：在已知范围内呈现某个数值——例如磁盘占用、密码强度、配额等（文档）
• ProgressBar：线性进度条，支持确定 / 不确定态、多种颜色与自定义格式（文档）
• ProgressCircle：基于 SVG 的环形进度条，可自定义轨道圆与填充圆（文档）
• Toolbar：将按钮、切换控件与分隔线按水平或垂直方向组合在一起的工具栏组件（文档）

Drawer

带有背景遮罩的滑出式浮层面板，支持顶部 / 底部 / 左侧 / 右侧四种放置位置、拖拽关闭手势以及多种背景遮罩变体。复合部件包括：Trigger、Backdrop、Content、Dialog、Header、Heading、Body、Footer、Handle、CloseTrigger。

放置位置：

配合表单使用：

Toggle Button

具备状态的切换按钮，可在选中与未选中之间切换。支持全部按钮变体与尺寸、仅图标模式，以及受控 / 非受控两种使用方式。

变体：

Toggle Button Group

单选或多选的切换按钮组。支持 attached（连接式）与 detached（分离式）两种布局、垂直方向、整宽展示，以及一个 Separator 子组件。

选择模式：

Attached 模式：

Meter

在已知范围内呈现某个数值——例如磁盘占用、密码强度、配额等。复合部件包括：Root、Output、Track、Fill。

颜色：

Progress Bar

线性进度指示器，支持确定 / 不确定态、颜色变体、多种尺寸以及自定义数值显示。复合部件包括：Root、Output、Track、Fill。

不确定态：

Progress Circle

基于 SVG 的环形进度条，提供 TrackCircle 与 FillCircle 两个子组件，便于直接控制 SVG。同时支持确定与不确定态。

自定义 SVG：

Toolbar

将按钮、切换按钮与分隔线组合到一个具备无障碍语义的工具栏中。支持水平或垂直方向，可与 ButtonGroup 和 ToggleButtonGroup 组合使用。

配合 Button Group 使用：

组件改进

ButtonGroup 的增强

新增的 ButtonGroup.Separator 子组件可在按钮之间显式插入一条视觉分隔线。在水平和垂直两种方向下都能正常工作。

Table 与 ListBox 的虚拟化

Table 与 ListBox 现在可以借助 React Aria 的 Virtualizer 来支持大数据集的虚拟化渲染。Virtualizer、TableLayout 和 ListLayout 都已从 @heroui/react 重新导出。

ButtonGroup 的方向

ButtonGroup 现在接受一个 orientation prop（"horizontal" | "vertical"），并在两种方向下都正确处理边框圆角与分隔线方向。根元素也已从 <div> 升级为 React Aria 的 Group，从而具备正确的 role="group" 语义。

ButtonGroup 的焦点环

成组按钮上的焦点环现在使用 ring-inset，确保焦点环留在按钮内部边界，而不会与相邻按钮重叠。

细粒度的组件引入

@heroui/react 现在支持按组件的子路径入口，方便更明确地按需引入（#6301）：

// 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，同时升级了相关包：

Bug 修复

• InputGroup：聚焦样式现在仅在实际的 input / textarea 获得焦点时（:has([data-slot]:focus)）才会触发，不再因 :focus-within 而被任意可聚焦的子元素触发（#6274）
• Avatar：fallback 元素现在会从父级继承 border-radius，而不再硬编码为 rounded-full，因此 className 覆盖能够正确生效（#6300）
• Modal 与 AlertDialog：背景遮罩的点击事件不会再透过 portal 传播到父级元素（#6297）
• Table：修复了 Firefox 中表头圆角与背景色溢出的问题（#6298）

链接

• 组件文档
• Figma Kit v3
• GitHub 仓库
• GitHub PR #6285

贡献者

感谢每一位为本次发布做出贡献的开发者！