2026 年 9 月 8 日

补丁版本：Toast 支持堆叠并在悬停时展开，Select 新增 ClearButton，Tabs 新增 align 变体，@heroui/react 再导出 Pressable、Focusable、OverlayTriggerStateContext 与 DisclosureStateContext，React Aria 升级到 1.21.0（react-aria@3.52.0）。同时修复了嵌套 data-theme 作用域与 Shadow DOM 中的主题 token、导出变体上的原生 :focus-visible 焦点环、Modal 级浮层被关闭中的 Popover 遮挡等问题，以及 ScrollShadow、Table、Drawer、NumberField、Accordion、Label 与 Tag 的若干问题。

安装

升级到最新版本：

npm i @heroui/styles@latest @heroui/react@latest

pnpm add @heroui/styles@latest @heroui/react@latest

yarn add @heroui/styles@latest @heroui/react@latest

bun add @heroui/styles@latest @heroui/react@latest

对等依赖已变更。 本次发布要求 react-aria-components@^1.21.0 与 react-aria@^3.52.0。若你锁定了这两个包的版本，请在同一次安装中一并升级，否则包管理器会报对等依赖冲突。

正在使用 AI 助手？ 对它说「Hey Cursor，把 HeroUI 升级到最新版本」。它会自动对比版本并应用必要变更。了解更多请参阅 HeroUI MCP 服务器。

新功能

Toast

Toast 现在会折叠成堆叠布局：最新的 Toast 以完整尺寸显示在最前，较旧的会缩小并按间距错开。悬停或聚焦堆叠时会展开所有可见 Toast；离开后再次折叠。自动关闭计时器在堆叠被悬停或聚焦时暂停，页面处于后台标签页时也会暂停。

堆叠：将较旧的 Toast 折叠到最前方 Toast 之后，支持悬停/聚焦展开、isExpanded 强制展开、toast.update() 原地更新内容、exitDuration 控制退场动画，以及 Alt+T / Escape / F6 键盘操作 (#6773)。

Select

Select 新增清除交互，且不会在 Select.Trigger 内嵌套按钮。将 Select.ClearButton 与 Value、Indicator 一起组合，并通过根组件的 onClear 监听清除。该控件渲染为仅指针可用的 span（aria-hidden）；键盘与读屏用户在组合了清除按钮且弹层关闭时，可用 Backspace 或 Delete 清除。

清除按钮：新增 Select.ClearButton 与根组件 onClear，无需非法嵌套按钮即可清除选中项 (#6796)。

Tabs

Tabs 可通过 align="start" | "center" | "end" 为整组标签设置对齐。默认仍为 center，现有 Tabs 外观不变。对齐使用逻辑属性（text-start / justify-start）以正确支持 RTL，并限定在标签列表上，使嵌套 Tabs 保持各自的对齐。

对齐：在 Tabs 上设置 align，无需在每个标签上重复 className 即可控制文本与内容对齐 (#6813)。

导出

基于 @heroui/react 的库可以从 HeroUI 导入 RAC 原语，而不必直接从 react-aria-components 导入。这样在 Vite 下会共用同一份实例，避免 Context 分裂以及 SSR 与客户端不一致。

RAC 原语：从 @heroui/react 再导出 Pressable、Focusable、OverlayTriggerStateContext 与 DisclosureStateContext (#6828)。

错误修复

主题：在 Shadow DOM 中通过 :root, :host 声明主题 token，使样式表被 adopt 进 shadow tree 后仍能应用圆角、颜色与深色模式 (#6841)。
Toast：toast.update 会保留未传入的 timeout 与 onClose，reset 会重启正在进行的倒计时，区域快捷键需精确匹配修饰键，去掉未使用的 viewTransitionName，并在 Toast 宽度变化时重新测量堆叠高度 (#6829、#6830、#6831、#6834、#6832)。
Accordion：默认触发器悬停背景需同时满足 :hover 与 data-hovered，自定义 hover:bg-* 在鼠标离开时不再闪一下默认颜色 (#6817)。
主题：补全嵌套 data-theme 作用域中缺失的 token（--surface-*-foreground、--field-placeholder），并将浮层阴影改为 --overlay-shadow，使局部深色/浅色区域能级联到组件 (#6803)。
焦点：将无法匹配的 :focus-visible:not(:focus) 替换为原生 :focus-visible，使使用 HeroUI 变体的原生锚点与按钮也能显示键盘焦点环，同时 React Aria 仍使用 [data-focus-visible="true"] (#6805)。
Label：在 Checkbox.Content、Switch.Content 与 Radio.Content 内将 Label 渲染为 span，避免嵌套 <label> 或复用分组标签的 id (#6807)。
浮层：将 Modal、AlertDialog 与 Drawer 提升到共享的 overlay z-index，并在 Popover 级浮层退出动画期间禁用指针事件，避免关闭中的 Dropdown / Select / Popover 盖住或拦截新打开 Modal 的点击 (#6798)。
Tag：将移除按钮的可点击区域扩大到 24×24，同时保持 12×12 图标，使多选 Autocomplete 芯片上的点击更可靠 (#6797)。
ScrollShadow：在支持的浏览器中通过 CSS 滚动时间线驱动淡出，使首屏绘制即正确、无需 hydration 后测量，从而避免闪烁；不支持的引擎与受控模式仍使用属性驱动，并合并消费者 style 以保留 --scroll-shadow-size / --scroll-shadow-offset (#6800)。
ScrollShadow：在内容尺寸变化后重新测量溢出，使 data-*-scroll 保持同步（包括 Tabs 箭头），并且 onVisibilityChange 只在真实状态变化时触发，而不是每次渲染 (#6812)。
ScrollShadow：通过观察内容变更来测量溢出，而不是在每次渲染时测量 (#6833)。
Calendar / RangeCalendar：对默认的 minValue 与 maxValue 做 memoize，避免日历状态在每次渲染时失效 (#6812)。
Button、Menu 与 Dropdown：将 will-change 合成器提示限制在按下和进出场动画状态，使静态文本在带有 transform 的浮层中保持清晰，包括 Modal 关闭后重新打开的场景 (#6779)。
Drawer：将拖拽手势限制在最近的所属 Drawer.Dialog，使嵌套抽屉的把手只关闭自身抽屉，而父抽屉保持打开且不发生位移 (#6780)。
Table：防止 typeahead 抢走嵌套可编辑控件的按键输入与焦点。keyboardNavigationBehavior 现已作为 prop 暴露，并默认设为 "tab"，同时保留非可编辑单元格中的 typeahead (#6781)。
NumberField：根据实际存在的步进槽位调整输入网格，没有递增或递减按钮时不再预留空白侧栏 (#6778)。
Toast：将自定义 style 与区域 CSS 变量及 Toast 堆叠样式合并，避免传入如 zIndex 等样式时丢失 --toast-width 导致 Toast 宽度塌缩 (#6794)。