2026 年 2 月 3 日

Beta 13 引入多行输入组件 TextArea、Button outline 变体，并为所有组件导出样式类名。本版本显著改进 Tabs（动画与变体命名更清晰）、将表单相关能力拆为独立原语、重构弹层动画系统以提升一致性与 Android 兼容性，并修复中文输入、主题色计算、Uniwind Pro 兼容、Bottom Sheet 打开与摇树（tree-shaking）等关键问题，整体提升开发者体验与组件可靠性。

安装

升级到最新版本：

npm i heroui-native@beta

pnpm add heroui-native@beta

yarn add heroui-native@beta

bun add heroui-native@beta

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

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

方式二：点击链接

📱 在 Expo Go 中打开演示应用

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

更新亮点

新组件

本版本新增 3 个重要组件：

TextArea：多行文本输入，带样式边框与背景，适用于较长内容。
Input：单行文本输入，带样式边框与背景；现作为独立于 TextField 的组件提供（此前仅 TextField.Input）。
CloseButton：可复用关闭按钮，用于 Dialog、Modal 等遮罩场景，样式在各遮罩间一致。

TextArea

TextArea 面向评论、消息、描述与较长表单字段等多行场景；可与 TextField 组合成完整表单结构，支持校验态与多种视觉变体。

特性：

多行输入，行数可配置
与 TextField 无缝组合
校验态与视觉反馈
primary / secondary 等变体
禁用与只读
className 与 styles 定制
完整无障碍支持

用法：

import { Description, Label, TextArea, TextField } from "heroui-native";

export function Example() {
  return (
    <TextField>
      <Label>Message</Label>
      <TextArea placeholder="Enter your message here..." />
      <Description>Please provide as much detail as possible.</Description>
    </TextField>
  );
}

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

相关 PR： #254

Input

Input 现可作为独立组件使用，提供带边框与背景的单行输入。此前仅能通过 TextField.Input 使用；现可单独使用，或与 TextField、ControlField 等组合。

特性：

单行输入，带样式边框与背景
独立使用或与表单组件组合
校验态与视觉反馈
primary / secondary 变体
禁用与只读
className 与 styles
完整无障碍支持

用法：

import { Description, Input, Label, TextField } from "heroui-native";

export function Example() {
  return (
    <TextField>
      <Label>Email</Label>
      <Input placeholder="Enter your email..." />
      <Description>We'll never share your email.</Description>
    </TextField>
  );
}

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

相关 PR： #247

CloseButton

CloseButton 为关闭 Dialog、Modal、Popover 等遮罩提供统一实现：跨遮罩一致样式、可配置图标属性，并与 Dialog、Popover、Select、Bottom Sheet 等集成。

特性：

各遮罩间关闭按钮样式一致
图标尺寸与颜色可配置
支持自定义子节点替换默认图标
禁用态
与 Dialog、Popover、Select、Bottom Sheet 集成
默认样式针对遮罩场景优化

用法：

import { CloseButton } from "heroui-native";

// 独立使用
<CloseButton onPress={handleClose} />

// 作为 Dialog、Popover、Select、Bottom Sheet 的一部分
<Dialog>
  <Dialog.Close />
</Dialog>

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

相关 PR： #237

新子组件

Tabs.Separator

Tabs 新增 Separator 子组件，在触发器之间提供随当前选项卡变化的显隐动画，便于做视觉分隔。

特性：

随活动选项卡变化的显隐过渡
betweenValues 控制显示区间
动画时长与不透明度可配置
可设为始终可见的静态分隔

用法：

import { Tabs } from "heroui-native";

<Tabs value={activeTab} onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.ScrollView>
      <Tabs.Indicator />
      <Tabs.Trigger value="general">
        <Tabs.Label>General</Tabs.Label>
      </Tabs.Trigger>
      <Tabs.Separator betweenValues={["general", "notifications"]} />
      <Tabs.Trigger value="notifications">
        <Tabs.Label>Notifications</Tabs.Label>
      </Tabs.Trigger>
    </Tabs.ScrollView>
  </Tabs.List>
</Tabs>

相关 PR： #228

组件改进

Button outline 变体

Button 新增 outline 变体：透明背景 + 边框，丰富按钮视觉层次。

改进：

新增 outline 有边框样式
与其他 Button 变体风格一致
outline 的悬停与聚焦态正确
与既有 Button API 无缝衔接

用法：

import { Button } from "heroui-native";

<Button variant="outline">Outline Button</Button>

相关 PR： #235

Tabs 指示条动画重构

Tabs 指示条动画由宽高动画改为 translateX 变换，过渡更顺滑、性能更好。

改进：

指示条迁移到 translateX
动画性能与流畅度提升
切换时视觉更一致
减少动画期间的布局重算

相关 PR： #227

Popover 改进箭头尺寸及与内容的视觉衔接。

改进：

箭头尺寸相对内容更合理
箭头与弹层连接更自然
对齐与间距优化

相关 PR： #243

表单组件拆分为原语

表单相关能力拆为独立原语，组合更灵活、职责更清晰。

改进：

表单能力原子化
复用性与组合性提升
关注点分离更好
自定义表单布局更自由

相关 PR： #247

Input Android 阴影修复

Input 为 Android 增加平台相关阴影，跨端视觉更一致。

改进：

Android 平台阴影
iOS / Android 观感对齐
Android 上层次（elevation）观感改善

相关 PR： #248

弹层动画系统重构

Popover、Select、Dialog、BottomSheet 的动画系统已重构：统一进出场逻辑、遮罩组合与内容动画，标准化各弹层行为并修复 Android 指针事件问题。

改进：

Dialog 等呈现统一使用 FadeInDown / FadeOutDown 等进出场
遮罩动画钩子同时支持基于 progress 与进出场两类动画
遮罩组合更多使用 Dialog.Overlay、Popover.Overlay，减少单纯 Pressable 包裹
修复影响弹层交互的 Android pointer events 问题
示例中显式写出 presentation（popover、dialog、bottom-sheet）
动画 API 简化，更易维护、跨组件更一致

相关 PR： #263

API 增强

细粒度导出以优化包体

库现为各组件提供细粒度导出路径，可按需 import 以减小包体。

新能力：

// 细粒度导入——仅需少量组件时推荐
import { HeroUINativeProvider } from "heroui-native/provider";
import { Button } from "heroui-native/button";
import { Card } from "heroui-native/card";

// 总入口导入——会拉取整库，适合大量使用组件时
import { Button, Card } from "heroui-native";

细粒度导入适合只用少数组件的场景；从 heroui-native 总入口导入会包含完整库，适合全站大量使用。

可用细粒度路径：

heroui-native/provider — Provider
heroui-native/[component-name] — 各组件
heroui-native/portal — Portal 工具
heroui-native/utils — 工具函数
heroui-native/hooks — 自定义 Hooks

重要：为控制包体，请在整个项目中一致地使用细粒度导入。只要存在一处从 heroui-native 总入口的导入，摇树优化策略即可能失效。

相关 PR： #233

样式类名导出

所有组件现导出对应样式类名，便于在代码中引用类名或搭建自定义主题方案。

新能力：

import { buttonClassNames } from "heroui-native";

const customStyles = {
  base: buttonClassNames.base,
  variant: buttonClassNames.variant,
};

相关 PR： #252

样式修复

样式优化

移除 quaternary 变体：删除第四级变体并打磨样式以提升一致性
多组件样式打磨：视觉一致性增强
阴影与圆角：跨组件阴影、圆角更统一
主题变量整理：简化变量并减少冗余 color-mix 计算

相关 PR： #246

⚠️ 破坏性变更

Tabs `variant` 重命名

Tabs 的 variant 由 pill / line 改为 primary / secondary，与其他组件命名更一致。

迁移：

// 之前
<Tabs variant="pill">{/* content */}</Tabs>
<Tabs variant="line">{/* content */}</Tabs>

// 之后
<Tabs variant="primary">{/* content */}</Tabs>
<Tabs variant="secondary">{/* content */}</Tabs>

可选项：

"primary" — 原 "pill"
"secondary" — 原 "line"

相关 PR： #236

Tabs 指示条动画实现变更

Tabs 指示条由 left 定位改为 translateX 变换以利用 GPU。若自定义过指示条动画，需更新配置。

迁移：

// 之前
<Tabs
  indicatorAnimation={{
    left: {
      type: "spring",
      config: { damping: 20, stiffness: 300 },
    },
  }}
>
  {/* content */}
</Tabs>

// 之后
<Tabs
  indicatorAnimation={{
    translateX: {
      type: "spring",
      config: { damping: 20, stiffness: 300 },
    },
  }}
>
  {/* content */}
</Tabs>

变更摘要：

TabsIndicatorAnimation 中由 left 改为 translateX
指示条定位基于 translateX 变换
指示条样式增加 left-0 基准类以保持初始位置
观感应与此前一致，仅底层实现变化

相关 PR： #227

Divider 更名为 Separator

Divider 已更名为 Separator，命名更统一，并避免与其他「分隔线」实现混淆。

迁移：

// 之前
import { Divider } from "heroui-native";
<Divider />

// 之后
import { Separator } from "heroui-native";
<Separator />

相关 PR： #238

移除 quaternary 变体

Surface 与 Card 已移除 quaternary 变体，简化设计系统。

迁移：

// 之前
<Surface variant="quaternary">{/* content */}</Surface>
<Card variant="quaternary">{/* content */}</Card>

// 之后：使用 default、secondary、tertiary 或自定义 className
<Surface variant="secondary">{/* content */}</Surface>
<Card variant="secondary">{/* content */}</Card>
<Surface className="bg-custom-quaternary">{/* content */}</Surface>

可用变体： "default"、"secondary"、"tertiary"

相关 PR： #246

表单原语拆分与重命名

表单拆分过程中若干组件重命名、结构调整，以获得更灵活的组合方式。

重命名：

FormField → ControlField
ErrorView → FieldError

迁移：

// 之前
import { FormField, ErrorView, TextField } from "heroui-native";
<FormField>
  <TextField.Input />
  <ErrorView>Error message</ErrorView>
</FormField>

// 之后
import { ControlField, FieldError, Input, TextField } from "heroui-native";
<ControlField>
  <Input />
  <FieldError>Error message</FieldError>
</ControlField>

移除 TextField.Input：

请改用独立 Input：

// 之前
import { TextField } from "heroui-native";
<TextField>
  <TextField.Input placeholder="Enter text..." />
</TextField>

// 之后
import { Input, TextField } from "heroui-native";
<TextField>
  <Input placeholder="Enter text..." />
</TextField>

组合方式：

RadioGroup、TextField、ControlField 现直接使用 Label、Description、FieldError：

import { ControlField, Description, FieldError, Input, Label, RadioGroup, TextField } from "heroui-native";

<TextField>
  <Label>Email</Label>
  <Input placeholder="Enter email..." />
  <Description>We'll never share your email.</Description>
  <FieldError>Invalid email address</FieldError>
</TextField>

<RadioGroup>
  <Label>Select option</Label>
  <RadioGroup.Item value="option1">
    <RadioGroup.Label>Option 1</RadioGroup.Label>
  </RadioGroup.Item>
  <Description>Choose one option</Description>
  <FieldError>Please select an option</FieldError>
</RadioGroup>

<ControlField>
  <Label>Custom Field</Label>
  <Input placeholder="Enter value..." />
  <Description>Additional information</Description>
  <FieldError>Validation error</FieldError>
</ControlField>

相关 PR： #247

CloseButton 与移除 Close 的 asChild

新增可复用 CloseButton；Dialog、Popover、Select、BottomSheet 的关闭实现统一基于该组件。各 *.Close 已移除 asChild。

迁移：

// 之前
import { Button, Dialog } from "heroui-native";
<Dialog>
  <Dialog.Close asChild>
    <Button>Cancel</Button>
  </Dialog.Close>
</Dialog>

// 之后：用受控 open + 自定义按钮处理关闭
import { Button, Dialog } from "heroui-native";
const [isOpen, setIsOpen] = useState(false);
<Dialog open={isOpen} onOpenChange={setIsOpen}>
  <Button onPress={() => setIsOpen(false)}>Cancel</Button>
</Dialog>

变更摘要：

新增 CloseButton，默认 variant="tertiary"、size="sm"、isIconOnly={true}
Dialog.Close、Popover.Close、Select.Close、BottomSheet.Close 内部基于 CloseButton
所有 Close 组件移除 asChild
Close 仍支持 Button 的 variant、size、iconProps 与自定义 children
使用完全自定义按钮时需自行处理关闭逻辑

相关 PR： #237

弹层动画系统重构（API）

弹层动画重构带来若干需改代码的 API 调整。

迁移要点：

从 Dialog.Root 移除 closeDelay、isDismissKeyboardOnClose
从 Dialog.Root 的 animation 移除自定义 entering/exiting（仅保留禁用类开关）；自定义进出场请在 Dialog.Content 上使用 Keyframe 动画配置
从 Dialog.Content 移除 isAnimatedStyleActive、onLayout
从 BottomSheet.Root 移除 isDismissKeyboardOnClose
BottomSheet.Overlay 的 animation 不再支持 entering/exiting
所有 Popover.Content、Select.Content 必须显式传入 presentation（由可选改为必填）
useBottomSheetAnimation() 不再返回 bottomSheetState；useDialogAnimation() 不再返回 dialogState

变更摘要：

Dialog.Root：移除 closeDelay、isDismissKeyboardOnClose；animation 类型由支持自定义进场的 DialogRootAnimation 收窄为仅禁用标志的 AnimationRootDisableAll
Dialog.Content：移除 isAnimatedStyleActive、onLayout
BottomSheet.Root：移除 isDismissKeyboardOnClose
BottomSheet.Overlay：animation 不再含 entering/exiting
Popover.Content、Select.Content：presentation 必填（此前可选，默认 "popover"）
上述动画钩子返回值精简

相关 PR： #263

问题修复

本版本包含以下修复：

Issue #181：修复 TextField 输入中文等多字节字符报错；现正确处理多字节与国际输入，含中日韩等语言。
Issue #219：修复 Button childrenToString() 在多子节点时返回 "[object Object]"；现正确处理 React 元素与复杂子树，避免错误字符串化。
Issue #232：修复 HeroUINativeProvider 与新版 Uniwind Pro 不兼容；现可正常配合最新 Uniwind。
Issue #259：修复 Bottom Sheet 在快速打开并随即进行手势操作后偶发无法再次打开等问题；进出场动画逻辑重构后已缓解。
Issue #261：修复 @gorhom/bottom-sheet 无法被摇树剔除的问题；未使用依赖可被更好剔除。

其他修复：

修复主题计算色在部分场景下数值错误
修复 childrenToString，避免错误地将 React 元素转为字符串

相关 PR：

#226
#239

链接

贡献者

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

Beta 13

安装

抢先体验

环境要求

如何访问

更新亮点

新组件

TextArea

Input

CloseButton

新子组件

Tabs.Separator

组件改进

Button outline 变体

Tabs 指示条动画重构

Popover 箭头尺寸与视觉衔接

表单组件拆分为原语

Input Android 阴影修复

弹层动画系统重构

API 增强

细粒度导出以优化包体

样式类名导出

样式修复

样式优化

⚠️ 破坏性变更

Tabs `variant` 重命名

Tabs 指示条动画实现变更

Divider 更名为 Separator

移除 quaternary 变体

表单原语拆分与重命名

CloseButton 与移除 Close 的 asChild

弹层动画系统重构（API）

问题修复

链接

贡献者

本页目录