2026 年 2 月 20 日

RC 2 继续向生产就绪推进：新增 SearchField、ListGroup、Slider 三个组件；Select 支持由类型安全泛型支撑的多选模式；Button 按压反馈 API 重构为统一的 feedbackVariant + animation；放宽对等依赖约束以更好兼容 Expo SDK 55。另含若干 Select 与 Avatar 的问题修复。

安装

升级到最新版本：

npm i heroui-native

pnpm add heroui-native

yarn add heroui-native

bun add heroui-native

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

抢先体验

通过预览应用在真机上体验 RC 2 的全部改进！你可以探索 SearchField、ListGroup、Slider、Select 多选模式、更新后的 Button 反馈 API，以及各项修复。

环境要求

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

如何访问

方式一：扫描二维码

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

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

方式二：点击链接

📱 在 Expo Go 中打开演示应用

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

更新亮点

新组件

本版本新增 3 个组件：

Slider：支持单值与区间模式、横/纵方向、自定义数字格式与弹簧动画拇指反馈。
ListGroup：基于 Surface 的分组列表，可按压项、前后缀槽位，默认右箭头导航指示。
SearchField：用于筛选与查询的复合组件，内置搜索图标、可清空输入与空值时自动隐藏清除按钮。

Slider

Slider 支持单值与区间（双拇指）模式、横纵布局、通过 Intl.NumberFormat 自定义数字格式，以及弹簧动画拇指反馈。原语层独立处理手势与数值逻辑，便于换肤实现复用。

特性：

复合子组件：Slider.Output、Slider.Track、Slider.Fill、Slider.Thumb
区间滑块：defaultValue/value 传入数组，在 Slider.Track 上使用渲染函数渲染多个拇指
orientation="vertical" 纵向
formatOptions 接受 Intl.NumberFormatOptions（货币、百分比、单位等）
基于 gesture-handler 的拖拽与轨道点击定位
数值钳制、步进与多拇指支持
可通过 animation 配置弹簧缩放拇指动画
无障碍：每个拇指 role="slider"，完整 accessibilityValue（min、max、now、text）
useSlider 暴露上下文供高级用法

用法：

import { Slider } from "heroui-native";

export function BasicSlider() {
  return (
    <Slider defaultValue={50} minValue={0} maxValue={100}>
      <Slider.Output />
      <Slider.Track>
        <Slider.Fill />
        <Slider.Thumb />
      </Slider.Track>
    </Slider>
  );
}

export function RangeSlider() {
  return (
    <Slider defaultValue={[20, 80]} minValue={0} maxValue={100}>
      <Slider.Output />
      <Slider.Track>
        {({ thumbs }) => (
          <>
            <Slider.Fill />
            {thumbs.map((_, i) => (
              <Slider.Thumb key={i} index={i} />
            ))}
          </>
        )}
      </Slider.Track>
    </Slider>
  );
}

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

相关 PR： #305

ListGroup

ListGroup 在 Surface 容器内渲染分组列表项，适用于设置页、菜单与内容浏览等导航列表模式。每项支持前缀、内容（标题 + 描述）与后缀槽位，默认带右箭头导航指示。

特性：

基于 Surface 的圆角容器与一致间距
复合子组件：ListGroup.Item、ListGroup.ItemPrefix、ListGroup.ItemContent、ListGroup.ItemTitle、ListGroup.ItemDescription、ListGroup.ItemSuffix
ItemSuffix 默认内置 ChevronRightIcon
可按压项，集成 PressableFeedback
槽位可完全自定义图标、徽标等

用法：

import { ListGroup } from "heroui-native";

export function Example() {
  return (
    <ListGroup>
      <ListGroup.Item onPress={() => console.log("Profile")}>
        <ListGroup.ItemContent>
          <ListGroup.ItemTitle>Profile</ListGroup.ItemTitle>
          <ListGroup.ItemDescription>Manage your account</ListGroup.ItemDescription>
        </ListGroup.ItemContent>
        <ListGroup.ItemSuffix />
      </ListGroup.Item>
      <ListGroup.Item onPress={() => console.log("Settings")}>
        <ListGroup.ItemContent>
          <ListGroup.ItemTitle>Settings</ListGroup.ItemTitle>
          <ListGroup.ItemDescription>App preferences</ListGroup.ItemDescription>
        </ListGroup.ItemContent>
        <ListGroup.ItemSuffix />
      </ListGroup.Item>
    </ListGroup>
  );
}

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

相关 PR： #302

SearchField

SearchField 为搜索与筛选场景提供专用输入，采用与 TextField 相同的复合组件模式：搜索图标、可清空输入、值为空时自动隐藏清除按钮。

特性：

复合子组件：SearchField.Group、SearchField.SearchIcon、SearchField.Input、SearchField.ClearButton
ClearButton 在值为空时自动隐藏，按压清除搜索文本
SearchIcon 支持自定义子节点替换默认放大镜 SVG
校验态视觉反馈
禁用态支持
与 Label、Description、FieldError 无缝集成

用法：

import { Label, SearchField } from "heroui-native";

export function Example() {
  return (
    <SearchField>
      <Label>Search</Label>
      <SearchField.Group>
        <SearchField.SearchIcon />
        <SearchField.Input placeholder="Search components..." />
        <SearchField.ClearButton />
      </SearchField.Group>
    </SearchField>
  );
}

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

相关 PR： #299

Select 多选模式

Select 现通过 selectionMode 支持多选。RootProps 对 SelectionMode 泛型化，TypeScript 按模式解析 value 与 onValueChange——单选为 SelectOption，多选为 SelectOption[]。

特性：

selectionMode="multiple" 可多选切换；多选模式下 closeOnPress 默认 false
类型安全泛型：RootProps<M> 通过 SelectValueType<M> 解析 value/onValueChange
Select.Value 使用 formatSelectedLabels 将多标签格式化为「Apple, Banana and Cherry」
单选模式完全向后兼容（默认）

用法：

import { Select } from "heroui-native";

export function MultiSelect() {
  return (
    <Select selectionMode="multiple">
      <Select.Trigger>
        <Select.Value placeholder="Select fruits..." />
        <Select.TriggerIndicator />
      </Select.Trigger>
      <Select.Portal>
        <Select.Content>
          <Select.Item value="apple" label="Apple" />
          <Select.Item value="banana" label="Banana" />
          <Select.Item value="cherry" label="Cherry" />
        </Select.Content>
      </Select.Portal>
    </Select>
  );
}

相关 PR： #298

新子组件

PressableFeedback.Scale

新增复合子组件，用于可选的缩放按压动画组合。PressableFeedback.Scale 可为任意可按压元素（如 ListGroup.Item）增加缩放反馈，而无需根级 PressableFeedback 管理缩放。

用法：

import { PressableFeedback } from "heroui-native";

<PressableFeedback.Scale>
  <ListGroup.Item onPress={handlePress}>
    {/* item content */}
  </ListGroup.Item>
</PressableFeedback.Scale>

相关 PR： #302

组件改进

Select 触发器与状态修复

Select 针对触发器与受控状态有多项修复。

改进：

自定义 className 现正确参与触发器样式计算，修复用户类名被静默丢弃的情况
useControllableState 在从受控切到非受控时重置内部状态，避免陈旧选中残留
触发器通过 onLayout 测量位置，正确支持 isDefaultOpen
触发器样式更新为 gap-3、py-3.5，值文本使用 flex-1 改善布局

相关 PR： #298

import { Button } from "heroui-native";

// 缩放 + 高亮（默认）
<Button feedbackVariant="scale-highlight">Press me</Button>

// 缩放 + 水波纹
<Button feedbackVariant="scale-ripple">Press me</Button>

// 仅缩放
<Button feedbackVariant="scale">Press me</Button>

// 自定义动画配置
<Button
  feedbackVariant="scale-highlight"
  animation={{ scale: 0.95, highlight: { color: "rgba(0,0,0,0.1)" } }}
>
  Press me
</Button>

animation 为按变体区分的联合类型，各反馈配置均有完整类型推导。

button.utils.ts 中新增 resolveAnimationObject 与 isAnimationDisabled，集中解析动画属性。

相关 PR： #302

依赖

放宽对等依赖约束

对等依赖版本约束已放宽为 caret（^）与范围（>=），替代偏紧的 tilde（~）或固定版本，便于使用方在较新依赖版本上解析，尤其 Expo SDK 55。

变更：

react-native-reanimated：~4.1.1 → ^4.1.1（允许次版本更新）
react-native-safe-area-context：~5.6.0 → ^5.6.0
react-native-svg：15.12.1 → ^15.12.1
react-native-worklets：0.5.1 → >=0.5.1

无运行时逻辑变更——此前已满足约束的项目无需修改即可继续工作。

相关 PR： #306

⚠️ 破坏性变更

Button 反馈 API

已移除 Button 上的 pressableFeedbackVariant、pressableFeedbackHighlightProps、pressableFeedbackRippleProps。请迁移到 feedbackVariant 与统一的 animation。

迁移：

更新所有 Button 反馈相关属性：

// 之前
<Button
  pressableFeedbackVariant="highlight"
  pressableFeedbackHighlightProps={{ color: "rgba(0,0,0,0.1)" }}
>
  Press me
</Button>

// 之后
<Button
  feedbackVariant="scale-highlight"
  animation={{ scale: 0.95, highlight: { color: "rgba(0,0,0,0.1)" } }}
>
  Press me
</Button>

变体映射：

"highlight" → "scale-highlight"（默认）
"ripple" → "scale-ripple"
"none" → "scale" 或 "none"

可选项：

"scale-highlight" — 缩小 + 高亮遮罩（默认）
"scale-ripple" — 缩小 + 水波纹
"scale" — 仅缩小
"none" — 无反馈动画

相关 PR： #302

问题修复

本版本包含以下修复：

Issue #291：修复 Select.Trigger 的 variant 被 className 覆盖的问题。传入触发器的自定义类名现正确参与样式计算，不再被静默丢弃。
Issue #294：兼容 react-native-worklets 0.7.x 与 react-native-reanimated 4.2.x（Expo SDK 55）。放宽对等依赖约束，接受上述新版本而不产生解析告警。

相关 PR：

#298
#306

文档更新

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

SearchField — 新组件文档：用法示例与 API 参考
ListGroup — 新组件文档：用法示例与 API 参考
Slider — 新组件文档：用法示例与 API 参考
Select — 多选模式、触发器 className 修复与受控状态改进
Button — 更新反馈 API 文档：feedbackVariant 与 animation
Avatar — 修复 asChild 图片属性展开说明
PressableFeedback — 新增 PressableFeedback.Scale 子组件文档

链接

贡献者

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

RC 2

安装

抢先体验

环境要求

如何访问

更新亮点

新组件

Slider

ListGroup

SearchField

Select 多选模式

新子组件

PressableFeedback.Scale

组件改进

Select 触发器与状态修复

Avatar asChild 图片修复

API 增强

Button 反馈 API 重构

依赖

放宽对等依赖约束

⚠️ 破坏性变更

Button 反馈 API

问题修复

文档更新

链接

贡献者

本页目录