v1.0.3

HeroUI Native v1.0.3 引入全新的 Text 排版基元，提供面向标题、段落与内联代码的复合 API；同时为 ScrollShadow 在反向列表下的渲染、Tabs 指示器在 RTL 布局下的对齐、以及自定义 Select.TriggerIndicator children 时的动画问题带来重要修复。本版本还对 Button、Chip、Input 的视觉样式进行了微调，将 Avatar 的 alt 属性改为可选，并修正 TextField 与 SearchField 的内部内边距行为。

安装

升级到最新版本：

npm i heroui-native

pnpm add heroui-native

yarn add heroui-native

bun add heroui-native

真机体验

新增

新组件

本版本新增 1 个 排版组件：

• Text：带语义 type 变体的排版基元组件，附带 Heading、Paragraph、Code 子组件。（文档）

Text

Text 组件是一个排版基元，通过语义化预设渲染样式化文本。它提供 Text.Heading、Text.Paragraph、Text.Code 等子组件构成的复合 API，并在 tailwind-variants 基础上叠加互不耦合的 align、color、weight、truncate 属性，使排版可以组合复用，无需在每个调用点重复定义样式。

特性：

• 语义化 type 变体：h1–h6、body、body-sm、body-xs、code
• Text.Heading 自动设置 accessibilityRole="header"，并将 type 收窄为标题级别
• Text.Paragraph 将 type 收窄为正文变体，适合长文本可读性
• Text.Code 渲染为 chip 样式的内联等宽文本，采用平台合适的 fontFamily（iOS 为 Menlo，其他平台为 monospace）
• RTL 感知的 align 属性，支持 start、center、end、justify（justify 仅 iOS 生效）
• 语义化 color 预设（default、muted），其他主题色可通过 className 外挂
• weight 覆盖：借助 tailwind-merge 始终优先于 type 暗含的字重
• truncate 布尔属性：等价于 numberOfLines={1}；显式 numberOfLines 始终优先

用法：

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

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

完整文档与示例见 Text 组件页面。

相关 PR： #400

组件改进

ScrollShadow 反向子列表支持

ScrollShadow 现已正确处理反向的可滚动子组件，如 <FlatList inverted> 或 <FlashList inverted>。

改进点：

• ScrollShadowRoot 现会读取可滚动子组件上的 inverted 属性，沿用既有的 childHorizontal 自动检测模式
• 内部交换驱动各视觉边缘的动画样式，使阴影渲染到正确的一侧
• 公共 API 无变化——仅当子组件设置 inverted={true} 时启用该修复，此前在此情况下渐变会出现在错误的边缘

此前，包裹反向列表时渐变阴影会渲染在顶部，而可滚动内容位于其下；即便仍有更多内容也不会出现底部阴影。修复后，反向 feed、聊天列表等反向滚动表面上的指示器方向已正确。

相关 PR： #398

Tabs RTL 指示器对齐

Tabs 的指示器在 React Native 处于 RTL 模式时定位现已正确。

改进点：

• 通过 tabs 测量上下文跟踪标签条的宽度
• 固定布局使用 Tabs.List 的布局宽度
• 滚动布局使用 Tabs.ScrollView 的内容宽度
• 仅当 I18nManager.isRTL 启用时，对指示器的 translateX 进行镜像

指示器使用绝对定位 left 锚点配合测量得到的 translateX。在 RTL 模式下，React Native 会自动翻转绝对锚点，但所测量的 transform 仍需手动镜像——本次修复内部完成了这一处理。固定与滚动两类标签列表均已修复，且公共 API 未变。

相关 PR： #396

Select 触发器指示器渲染统一

Select 的 Select.TriggerIndicator 现无论使用默认图标还是自定义 children，都会一致地应用展开/收起的旋转动画。

改进点：

• 自定义 children 现可获得与默认图标相同的动画容器样式
• 通过 children ?? <ChevronDownIcon /> 将 ChevronDownIcon 作为回退渲染
• 将此前分散的渲染分支合并为统一的渲染路径

此前，向 Select.TriggerIndicator 传入自定义 children 会绕过旋转动画，导致开合时指示器保持静止。统一分支确保旋转动画始终生效，且公共 API 未变。

相关 PR： #409

API 增强

Avatar 的 alt 属性变为可选

Avatar 的 alt 属性现已可选，默认为 'Avatar'，在保留无障碍支持的同时，减少装饰性或语境明确场景下的样板代码。

新能力：

import { Avatar } from "heroui-native";

<Avatar>
  <Avatar.Image source={{ uri: "https://example.com/avatar.jpg" }} />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>;

显式传入 alt 的既有代码继续正常工作——该属性仅在缺省时获得一个合理的默认值。RootProps 类型现已反映为 alt?: string，并通过 JSDoc 标注 @default 'Avatar'，组件文档同步更新。

相关 PR： #404

样式修复

Button、Chip、Input 样式微调

对 Button、Chip、Input 的尺寸与色彩样式进行了微调，统一改用 Tailwind 工具类与语义化的 soft 颜色令牌。

修复：

• Button：尺寸改用 Tailwind 高度工具类（h-10、h-12、h-14），不再使用任意像素值；sm 高度由 36px 调整为 40px，提升触控目标的人体工学
• Chip：md/lg 的垂直内边距微调（py-[3px] → py-1，py-1 → py-1.5），间距更协调
• Chip：soft 变体改用语义化 bg-{color}-soft 令牌，取代基于不透明度的 bg-{color}/15 背景
• Input：由 py-3.5 改为 min-h-12，无论内容如何字段都保持稳定高度
• Input：primary 变体的边框现正确使用 border-field-border 令牌，而非 border-field

Button sm 尺寸（+4px）与 Chip md/lg 内边距上的像素级差异建议进行视觉回归确认。无 API 变更——仅更新了 button.styles.ts、chip.styles.ts、input.styles.ts 中的样式令牌。

相关 PR： #406

TextField 与 SearchField 内部内边距修复

TextField 与 SearchField 不再对嵌套的 Label、Description、FieldError 施加额外的水平内边距。

修复：

• TextField 现在向其 FormFieldContext 提供 hasFieldPadding: false
• SearchField 现在向其 FormFieldContext 提供 hasFieldPadding: false
• 渲染在上述字段内的 Label、Description、FieldError 不再继承额外的 px-1.5 侧边距
• 所有表单字段容器（ControlField、RadioGroup、TagGroup 已采用 hasFieldPadding: false）的视觉对齐现已统一

此次变更仅涉及两处为 FormFieldContext 提供值的 useMemo。如果你此前依赖这一非预期的内部内边距，可通过为受影响的子组件添加 className="px-1.5" 恢复原有间距。

相关 PR： #407

问题修复

本版本包含以下修复：

• Issue #334：修复 RTL 布局下 Tabs.Indicator 的定位错乱。指示器以绝对定位 left 锚点配合测量的 translateX 实现位移；在 RTL 模式下 React Native 会自动翻转锚点，但测量得到的 transform 仍需手动镜像。tabs 测量上下文现会跟踪标签条宽度，仅当 I18nManager.isRTL 启用时镜像 translateX，固定与滚动两类标签列表均已修复。
• Issue #393：修复 ScrollShadow 忽略子组件 inverted 属性的问题。ScrollShadowRoot 现会读取可滚动子组件上的 inverted（沿用既有的 childHorizontal 自动检测），并交换驱动各视觉边缘的动画样式，使反向 feed 与聊天式列表上的渐变出现在正确的一侧。

相关 PR：

• #396
• #398

文档更新

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

• Text — 新组件文档，含结构、用法与完整 API 参考
• Avatar — alt 属性记为可选，默认值 'Avatar'
• 组件总览 — 在既有分类外新增 Typography 分类

链接

• 组件文档
• GitHub 仓库

贡献者

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