v1.0.4

HeroUI Native v1.0.4 将排版基元 Text 重命名为 Typography，让出 React Native 自身的 Text 名称，同时更贴近语义化排版用法；既有的 Text 导出保留为弃用别名，可平滑升级。本版本还在 Alert、Avatar、Button、Chip、Toast 中调整了 soft 前景色令牌，使其在 soft 背景上具备更好的对比度；新增可选的 heroui-native/styles/vibrant 配色；为 Menu、Popover、Select 补充 iOS 原生模态偏移的处理说明；并将示例应用升级到 Expo 56 / React Native 0.85。

安装

升级到最新版本：

npm i heroui-native

pnpm add heroui-native

yarn add heroui-native

bun add heroui-native

真机体验

新增

Typography 组件（由 Text 重命名而来）

库内的排版基元已从 Text 重命名为 Typography，避免与 React Native 内建的 Text 重名，并更准确地体现其作为语义化排版系统的定位。组件的 API、变体与行为保持不变——只是公开名称发生变化。

import { Typography } from "heroui-native";
import { View } from "react-native";

export function Example() {
  return (
    <View className="flex-1 justify-center px-5 gap-4">
      <Typography.Heading type="h1">Welcome</Typography.Heading>
      <Typography.Heading type="h3">Getting Started</Typography.Heading>
      <Typography.Paragraph>
        This is a body paragraph rendered with the Typography component.
      </Typography.Paragraph>
      <Typography.Paragraph color="muted" type="body-sm">
        Smaller supporting text for captions or footnotes.
      </Typography.Paragraph>
      <Typography.Code>npm install heroui-native</Typography.Code>
    </View>
  );
}

变更要点：

• 主导出改为 Typography，子组件为 Typography.Heading、Typography.Paragraph、Typography.Code
• 新增 typographyClassNames 样式 API 与 Typography* 类型别名，取代原先的 Text* 命名
• 既有的 Text、textClassNames 与 Text* 类型作为弃用的重导出保留以兼容旧代码
• 组件目录中的示例页由 text 重命名为 typography
• JSDoc 与组件文档更新为引用 Typography 以及新的文档 URL

相关 PR： #417

鲜亮主题配色（可选）

新增可选的 heroui-native/styles/vibrant 样式表，适合希望在 soft 变体上保持更饱和品牌色的应用。它在保留调整后的柔和前景令牌带来的可读性改进的同时，仍为 soft 背景上的图标与文字保留较高的色彩饱和度。

用法：

// 默认调整后的柔和前景配色
import "heroui-native/styles";

// 或者，启用鲜亮配色
import "heroui-native/styles";
import "heroui-native/styles/vibrant";

在引入基础样式之后再引入 heroui-native/styles/vibrant，即可用更饱和的取值覆盖柔和前景令牌。无需修改任何组件代码即可启用。

相关 PR： #420

组件改进

多组件柔和前景色调整

Alert、Avatar、Button、Chip、Toast 现使用新的 *-soft-foreground 主题令牌渲染 soft 背景上的标签与图标，呈现更好的对比度，并在亮色与暗色主题下保持更统一的视觉效果。

改进点：

• theme.css 中通过 color-mix 计算柔和前景令牌（accent-soft-foreground、success-soft-foreground、warning-soft-foreground、danger-soft-foreground、default-soft-foreground），提升 soft 背景上的可读性
• Alert、Avatar、Button、Chip、Toast 的样式（及其内部 hooks）改为使用新的柔和前景令牌，不再直接使用 text-accent、text-success 等原始语义色
• 新增可选的 heroui-native/styles/vibrant 导出，为希望保留饱和品牌色的应用保留更鲜亮的 soft 变体外观
• 示例应用中 Alert、Avatar、Button、Chip、Toast 的演示同步更新以匹配新的取色方式

组件属性与公开 API 均无变化——仅 soft 变体的取色发生变化。沿用默认主题的应用将开箱获得 soft 变体上更柔和、可读性更佳的图标与标签颜色。

相关 PR： #420

TextArea 垂直内边距修复

TextArea 现已应用合适的内部垂直内边距，多行内容不再紧贴输入区上边缘。

改进点：

• TextArea 现使用 h-32 py-2，提供一致的内部间距
• 无 API 变更——仅为组件内的样式调整

相关 PR： #421

API 增强

useThemeColor 令牌更新

useThemeColor hook 新增表面色与柔和色相关令牌，并对遮罩背景令牌进行了重命名以更清晰表达语义。

新能力：

import { useThemeColor } from "heroui-native";

const colors = useThemeColor([
  "default-soft",
  "default-soft-foreground",
  "surface-foreground",
  "backdrop",
]);

变更：

• 新增 default-soft 与 default-soft-foreground 令牌
• 新增表面前景色令牌（如 surface-foreground），可显式取用表面文字颜色
• 将 overlay-backdrop 重命名为 backdrop，与底层 CSS 变量命名保持一致

如果你使用了已移除的 useThemeColor 键（on-surface-*）或旧的 overlay-backdrop 键，请改用更新后的令牌名。组件属性与视觉默认值保持不变。

相关 PR： #420

依赖

@gorhom/bottom-sheet 对等依赖范围更新

@gorhom/bottom-sheet 的对等依赖范围由 ^5.2.8 升级到 ^5.2.9。如果你的应用使用 HeroUI Native 的 BottomSheet（或 Menu / Popover / Select 配合 presentation="bottom-sheet"），请确保安装兼容版本：

npm i @gorhom/bottom-sheet@^5.2.9

这是本版本对消费者唯一的对等依赖变更。库的 react（>=19.0.0）与 react-native（>=0.81.0）对等依赖范围保持不变。

相关 PR： #421

示例应用升级至 Expo 56 / React Native 0.85

仓库内的示例应用升级到了最新的 Expo 与 React Native 工具链。这不会直接影响库的消费者，但为运行示例的贡献者带来收益：

• Expo 56
• React Native 0.85.3
• React 19.2.3
• React Native Reanimated 4.3.1
• react-native-worklets 0.8.3
• Uniwind ^1.6.3

本次升级还包含以下整理：

• 重写 metro.config.js，将对等依赖解析锁定到示例的 node_modules，修复当 uniwind 或 react 从 workspace 根解析出两份副本时 Hermes 抛出的「Maximum call stack size exceeded」崩溃
• 在 input-otp 与展示页中以 StyleSheet.absoluteFill 替换已弃用的 StyleSheet.absoluteFillObject
• 将 useFocusEffect / useHeaderHeight 的导入迁移至 expo-router
• 移除未使用的 example/src/components/safe-area-view.tsx、eas.json 以及陈旧的 newArchEnabled / edgeToEdgeEnabled 标记
• 示例应用的 slug/bundle 重命名为 heroui-native-oss；调整 Android 上 WithStateToggle 的内边距

相关 PR： #421

文档

Menu、Popover、Select 的 iOS 原生模态偏移说明

Menu、Popover、Select 文档新增**原生模态（iOS）**章节，解释当触发器位于以原生模态（presentation: "modal" | "formSheet" | "pageSheet"）呈现的页面内时，遮罩内容为何会向上偏移渲染，以及如何补偿。

改进点：

• 各组件文档说明了 Fabric / FullWindowOverlay 的坐标不一致：触发器坐标相对于模态原点，而遮罩锚定在窗口
• 文档化了配合 react-native-safe-area-context 中 useSafeAreaInsets 使用的 offset={insets.top} 推荐方案
• 提供示例应用中相关文件（popover-native-modal.tsx、select-native-modal.tsx）的链接，便于查阅完整用法

用法示例：

import { useSafeAreaInsets } from "react-native-safe-area-context";
import { Popover } from "heroui-native";

const insets = useSafeAreaInsets();

<Popover.Content presentation="popover" offset={insets.top + 20}>
  {/* ... */}
</Popover.Content>;

这是纯文档变更，未改动任何 API 或运行时行为。

相关 PR： #419

问题修复

本版本包含以下修复：

• Issue #405：补充了在 React Navigation 原生模态中 Menu 渲染错位的处理方案。Menu 文档新增**原生模态（iOS）**章节，解释 Fabric / FullWindowOverlay 的坐标不一致，并演示如何用 useSafeAreaInsets 配合 offset={insets.top} 补偿。
• Issue #418：修复将示例应用升级到 Expo 56 后出现的 Hermes 崩溃（「Maximum call stack size exceeded」）及 BottomSheet 内容不可见的问题。示例的 metro.config.js 现已将对等依赖解析（react、react-native、uniwind 等）锁定到示例的本地 node_modules，防止从 workspace 根加载到重复副本。

相关 PR：

• #419
• #421

弃用

Text 排版导出

Text 组件与相关导出现已弃用，推荐使用 Typography。既有导入仍可继续工作，不会产生运行时错误——仅会在 TypeScript / IDE 中提示弃用。请在未来某个大版本移除弃用别名之前完成迁移。

弃用 → 推荐：

// 弃用（仍可用）
import { Text, textClassNames, type TextProps } from "heroui-native";

<Text.Heading type="h1">Welcome</Text.Heading>;

// 推荐
import {
  Typography,
  typographyClassNames,
  type TypographyProps,
} from "heroui-native";

<Typography.Heading type="h1">Welcome</Typography.Heading>;

相关 PR： #417

文档更新

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

• Typography — 组件由 Text 重命名而来；完整 API、Anatomy 与用法已更新
• Menu — 新增**原生模态（iOS）**章节，含 offset={insets.top} 方案
• Popover — 新增**原生模态（iOS）**章节，含 offset={insets.top} 方案
• Select — 新增**原生模态（iOS）**章节，含 offset={insets.top} 方案
• 快速开始 — 可选对等依赖 @gorhom/bottom-sheet 更新到 ^5.2.9

链接

• 组件文档
• GitHub 仓库

贡献者

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