v1.0.0

🎉 HeroUI Native 正式发布 v1.0.0——这是首个稳定版本，标志着库已从 beta 与候选发布阶段毕业，成为可用于生产环境的 React Native 应用基础。伴随这一里程碑，本版本还包含全新的 LinkButton 组件、子菜单冲突处理、可选的 @gorhom/bottom-sheet 对等依赖，以及针对 useThemeColor 的更强类型安全。

安装

升级到最新版本：

npm i heroui-native

pnpm add heroui-native

yarn add heroui-native

bun add heroui-native

抢先体验

通过我们的预览应用，在真机上体验 v1.0.0 的全部改进！你可以探索全新的 LinkButton 组件、改进后的子菜单行为，以及各项修复。

环境要求

请确保手机已安装最新版本的 Expo Go。

如何访问

方式一：扫描二维码

使用手机相机或 Expo Go 应用扫描：

Android 用户请注意： 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。

方式二：点击链接

📱 在 Expo Go 中打开演示应用

若设备已安装 Expo Go，将自动在其中打开应用。

更新亮点

LinkButton 组件

全新的 LinkButton 复合组件会渲染 ghost 变体按钮，且无高亮反馈，适用于「服务条款」「隐私政策」等行内链接式交互。它完全复用现有 Button 基础设施，并在内部强制 ghost 变体且关闭高亮反馈。

特性：

• 复合子组件：LinkButton.Label，用于样式化文本内容
• 内部强制 ghost 变体——不对外暴露 variant 属性
• 通过 resolveAnimationObject 默认关闭高亮反馈
• h-auto p-0 基础类移除默认按钮高度与内边距，便于行内使用
• 合并使用方动画配置时仍保持 highlight: false

用法：

import { LinkButton } from "heroui-native";

export function TermsLink() {
  return (
    <LinkButton onPress={() => openURL("https://example.com/terms")}>
      <LinkButton.Label>Terms of Service</LinkButton.Label>
    </LinkButton>
  );
}

相关 PR： #341

组件改进

子菜单单开约束与点击背景关闭

Menu 子菜单系统已重构为按 ID 跟踪当前子菜单，而非简单布尔值，从而在同级子菜单之间强制「同时仅开一个」。子菜单打开时，会在菜单内容区域上方渲染可点击的背景层，用户点击外部即可关闭。

改进：

• openSubMenuId 取代布尔标记——同一时间只能有一个子菜单处于打开状态；打开新的会自动关闭上一个
• 子菜单打开时，在菜单内容上渲染 Pressable 遮罩，支持点击关闭
• 非当前打开的子菜单触发器通过新的 isOtherSubMenuOpen 样式变体获得 opacity-40 与 pointer-events-none
• 打开的子菜单内容使用 z-50，关闭的为 z-40，避免层叠问题
• 演示应用新增「两个子菜单」示例，展示同一菜单中的多个子菜单

相关 PR： #343

Button Label 的 ref 类型修复

ButtonLabel 的 ref 类型已从 View 更正为 TextRef，并从 button.tsx 中移除了未使用的 View 导入，使 ref 类型与实际渲染元素一致。

相关 PR： #341

API 增强

用于 useThemeColor 的 ThemeColorValue 品牌类型

useThemeColor 在单次取色调用时现返回 ThemeColorValue 品牌类型，误用数组解构时 IDE 会立即将类型标为 never。非空断言运算符（!）也已替换为安全的空值合并回退。

新行为：

import { useThemeColor } from "heroui-native";

// 正确 — 直接赋值
const mutedColor = useThemeColor("muted");

// 错误 — IDE 会立即标出 `never` 类型
const [color] = useThemeColor("muted"); // color: never

ThemeColorValue 继承自 string，因此凡可接受 string 处均可赋值。现有调用点在运行时不受影响。_colorValueBrand 符号以 declare const 声明，无运行时体积。

相关 PR： #337

公开钩子 useBottomSheetAwareHandlers

useBottomSheetAwareHandlers 现已作为公开 API 导出，便于在 Bottom Sheet 内显式控制键盘避让与 Input、InputOTP 的衔接。此前在 Input 与 InputOTP 上可用的隐式 isBottomSheetAware 属性已被取代。

用法：

import { useBottomSheetAwareHandlers, Input } from "heroui-native";

export function BottomSheetInput() {
  const { onFocus, onBlur } = useBottomSheetAwareHandlers();

  return <Input onFocus={onFocus} onBlur={onBlur} placeholder="Type here..." />;
}

相关 PR： #347

⚠️ 破坏性变更

Bottom Sheet 内的 Input 与 InputOTP

已从 Input 与 InputOTP 移除 isBottomSheetAware 属性。此前 Bottom Sheet 内的键盘避让在底层自动处理；现在必须显式使用 useBottomSheetAwareHandlers 并自行传入处理器。这样可减轻 Input 组件负担，去掉隐式 @gorhom/bottom-sheet 导入，使该包对不使用 Bottom Sheet 的项目成为可选对等依赖。

迁移：

// 之前
<Input isBottomSheetAware placeholder="Type here..." />

// 之后
import { useBottomSheetAwareHandlers } from "heroui-native";

const { onFocus, onBlur } = useBottomSheetAwareHandlers();
<Input onFocus={onFocus} onBlur={onBlur} placeholder="Type here..." />

凡在 BottomSheet 内渲染的 Input 或 InputOTP 均需按此调整；在 Bottom Sheet 外使用的组件不受影响。

相关 PR： #347

问题修复

本版本包含以下修复：

• Issue #330：修复 Input 在模块顶层无条件导入 @gorhom/bottom-sheet 的问题，即使 isBottomSheetAware 为 false。现通过可选的 try/catch 包装懒加载该包，不使用 Bottom Sheet 的项目无需再安装它。

• Issue #340：修复子菜单内容出现在同级子菜单触发器后方的问题。子菜单系统现按 ID 跟踪活动子菜单、强制单开，并应用正确的 z-index 分层（打开 z-50，关闭 z-40）。

相关 PR：

• #347
• #343

文档更新

以下文档页面已随本版本更新：

• LinkButton — LinkButton 复合组件文档：结构分解、用法示例与 API 参考
• Menu — 更新子菜单文档：单开约束与点击背景关闭行为
• Input — 更新 Bottom Sheet 用法示例，采用 useBottomSheetAwareHandlers 模式
• InputOTP — 同上，Bottom Sheet 示例采用 useBottomSheetAwareHandlers

链接

• 组件文档
• GitHub 仓库

贡献者

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