RC 2

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

安装

升级到最新版本：

<Tabs items={["npm", "pnpm", "yarn", "bun"]}> <Tab value="npm">

npm i heroui-native

抢先体验

通过预览应用在真机上体验 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 自定义数字格式，以及弹簧动画拇指反馈。原语层独立处理手势与数值逻辑，便于换肤实现复用。

<NativeVideoPlayerView target="component" slug="slider" srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-light.mp4" srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-dark.mp4" />

特性：

• 复合子组件：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 容器内渲染分组列表项，适用于设置页、菜单与内容浏览等导航列表模式。每项支持前缀、内容（标题 + 描述）与后缀槽位，默认带右箭头导航指示。

<NativeVideoPlayerView target="component" slug="list-group" srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-light.mp4" srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-dark.mp4" />

特性：

• 基于 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 相同的复合组件模式：搜索图标、可清空输入、值为空时自动隐藏清除按钮。

<NativeVideoPlayerView target="component" slug="search-field" srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-light.mp4" srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-dark.mp4" />

特性：

• 复合子组件：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}>
  </ListGroup.Item>
</PressableFeedback.Scale>

相关 PR： #302

组件改进

Select 触发器与状态修复

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

改进：

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

相关 PR： #298

Avatar asChild 图片修复

Avatar 的 AvatarImage 在向底层原语转发时正确分离 source、style 与 asChild 及其余属性，修复使用 asChild 时错误将全部属性展开到图片组件的问题。

相关 PR： #298

API 增强

Button 反馈 API 重构

Button 的按压反馈 API 重构为统一的类型安全 feedbackVariant + animation，取代此前多属性拼写。

新能力：

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 子组件文档

链接

• 组件文档
• GitHub 仓库

贡献者

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