2026 年 7 月 21 日

HeroUI Native v1.0.6 通过将每个组件从内联 Tailwind 类名字符串迁移到 src/styles/components 下专用的 BEM 命名 CSS 文件来集中管理样式，同时让 tv() 插槽仅作为对这些类的轻量引用，从而更易于覆盖与维护。本版本还修复了一个 PortalHost 协调（reconciliation）缺陷：在不同屏幕间，Sheet、Dialog 与 Popover 可能会相互继承彼此的状态——产生「幽灵」状态的已打开 Sheet——现在通过按唯一名称为每个 Portal 子树设置 key 来解决该问题。

安装

升级到最新版本：

npm i heroui-native

pnpm add heroui-native

yarn add heroui-native

bun add heroui-native

使用 AI 助手？ 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 HeroUI Native MCP 服务器。

真机体验

Don't have the HeroUI Native app yet? Download it below.

在 App Store 下载在 Play Store 下载

样式

组件样式迁移到专用的 CSS 类

每个组件的样式已从各个 *.styles.ts 文件中冗长的内联 Tailwind 类名字符串，迁移到 src/styles/components 下专用的 BEM 命名 CSS 文件，并通过 src/styles/index.css 接入。tv() 插槽现在仅作为对这些 CSS 类的轻量引用，从而集中管理样式，使组件更易于覆盖与维护。

改进点：

将全部约 40 个组件的样式抽取为 BEM 结构的 .css 文件，并通过 src/styles/index.css 接入
让 tv() 插槽仅作为对新 CSS 类的轻量引用，而非内联 Tailwind 字符串
新增 element-disabled 工具类
清理相关的工具类与依赖

组件的公开 API 未变，因此无需修改代码。消费者需确保已加载 src/styles/index.css，组件才能正确渲染。

相关 PR： #452

问题修复

PortalHost 幽灵 Sheet

PortalHost 此前将所有已注册的 Portal 渲染为一个未设置 key 的数组，因此 React 会按索引进行协调。当某个 Portal 在列表中途注册或注销时——例如某个屏幕卸载时——相邻的 Portal 索引会发生偏移，导致 React 把一个 Portal 的实时组件状态嫁接到另一个 Portal 的内容上。对于底部 Sheet 而言，这会让其继承内部 Sheet 实例及其动画位置，于是一个已关闭的 Sheet 可能显示为完全打开（「幽灵」Sheet），而一个已打开的 Sheet 则可能继承到已关闭的实例而始终无法显示。

现在每个 Portal 子树都按其唯一的 Portal 名称设置 key，因此 React 会按身份而非数组位置来追踪 Portal。这修复了 BottomSheet、Dialog、Popover 与 Select 各类 Portal 上的幽灵 Sheet 行为，也很可能是底部 Sheet 间歇性无法显示的根因。

本版本包含针对以下问题的修复：

Issue #441：修复 PortalHost 将 Portal 渲染为未设置 key 的数组的问题——当某个屏幕卸载时，会导致 Sheet 与 Dialog 相互继承状态，从而出现显示无关内容的「幽灵」已打开 Sheet。现在 Portal 按名称设置 key，使每个子树都按身份被追踪。

相关 PR： #442

链接

贡献者

感谢所有为本版本做出贡献的朋友！

v1.0.6

本页目录