Pressable

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

Pressable 是一个核心组件包装器，能够检测其子元素上各种按压交互的不同阶段。

tsx

<Pressable onPress={onPressFunction}>
  <Text>I'm pressable!</Text>
</Pressable>

工作原理

在被 Pressable 包裹的元素上：

• 按压激活时会调用 onPressIn

• 按压手势取消时会调用 onPressOut

触发 onPressIn 后，将发生以下两种情况之一：

1. 用户抬起手指，依次触发 onPressOut 和 onPress

2. 若用户在抬起手指前按压超过 500 毫秒，则触发 onLongPress（抬起手指时仍会触发 onPressOut）

手指并非精密操作工具，用户常会误触错误元素或错过激活区域。为此，Pressable 提供了可选的 HitRect，用于定义可检测按压的包裹元素外围距离。按压可在 HitRect 区域内任意位置开始。

PressRect 允许按压在保持激活状态时超出元素及其 HitRect 范围，同时仍符合"按压"条件——想象您按压按钮时手指缓慢滑离的场景。

触摸区域永远不会超出父视图边界，当触摸点命中两个重叠视图时，兄弟视图的 Z-index 始终优先

You can set HitRect with hitSlop and set PressRect with pressRetentionOffset.

Pressable 使用 React Native 的 Pressability API。有关 Pressability 状态机流程及其工作原理的更多信息，请查阅 Pressability 实现。

示例

属性

android_disableSound

Android

为 true 时，按压时不播放 Android 系统音效

Type	Default
boolean	false

android_ripple

Android

启用 Android 涟漪效果并配置其属性

Type
RippleConfig

children

子元素或接收布尔值的函数（表示组件当前是否处于按压状态）

Type
React Node

unstable_pressDelay

按压后等待触发 onPressIn 的时长（毫秒）

Type
number

delayLongPress

从 onPressIn 到触发 onLongPress 的时长（毫秒）

Type	Default
number	500

disabled

是否禁用按压行为

Type	Default
boolean	false

hitSlop

设置元素外部可检测按压的附加距离

Type
Rect or number

onHoverIn

悬停激活时调用（用于提供视觉反馈）

Type
({ nativeEvent: MouseEvent }) => void

onHoverOut

悬停取消时调用（用于撤销视觉反馈）

Type
({ nativeEvent: MouseEvent }) => void

onLongPress

当 onPressIn 后的持续时间超过 500 毫秒时调用（可通过 delayLongPress 自定义此时长）

Type
({nativeEvent: PressEvent}) => void

onPress

在 onPressOut 之后调用

Type
({nativeEvent: PressEvent}) => void

onPressIn

触摸开始瞬间调用，在 onPressOut 和 onPress 之前触发。

Type
({nativeEvent: PressEvent}) => void

onPressMove

按压位置移动时调用

Type
({nativeEvent: PressEvent}) => void

onPressOut

触摸释放时调用。

Type
({nativeEvent: PressEvent}) => void

pressRetentionOffset

在触发 onPressOut 之前，视图外部可被视为按压事件的额外距离。

Type	Default
Rect or number	{bottom: 30, left: 20, right: 20, top: 20}

style

可以是视图样式对象，或是接收组件当前按压状态（布尔值）并返回视图样式的函数。

Type
View Style or ({ pressed: boolean }) => View Style

testOnly_pressed

仅用于文档或测试场景（例如快照测试）。

Type	Default
boolean	false

类型定义

RippleConfig

用于配置 android_ripple 属性的波纹效果。

Type
object

属性：

Name	Type	Required	Description
color	color	No	Defines the color of the ripple effect.
borderless	boolean	No	Defines if ripple effect should not include border.
radius	number	No	Defines the radius of the ripple effect.
foreground	boolean	No	Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.