跳到主要内容

Pressable

Pressable 是一个 Core Component 包装器，可检测其任意已定义子元素上的各种按压交互阶段。

React TSX
<Pressable onPress={onPressFunction}>
  <Text>我可以被按压！</Text>
</Pressable>

工作原理​

对于被 Pressable 包裹的元素：

  • 在按压被激活时，会调用 onPressIn。
  • 在按压手势被取消时，会调用 onPressOut。

在按下 onPressIn 之后，会发生以下两种情况之一：

  1. 这个人会移开手指，触发 onPressOut，随后是 onPress。
  2. 如果这个人移开手指前按住超过 500 毫秒，则会触发 onLongPress。（在移开手指时，onPressOut 仍然会触发。）
按压事件顺序示意图。

手指并不是最精确的工具，用户经常会不小心激活错误的元素，或者错过激活区域。为此，Pressable 提供了一个可选的 HitRect，你可以用它来定义触点距离包裹元素多远时仍可被识别。按压可以从 HitRect 内的任意位置开始。

PressRect 允许按压在保持激活状态并仍可被视为一次“按压”的同时，移动到元素及其 HitRect 之外——可以把它想象成手指从正在按下的按钮上缓慢滑开。

备注

触摸区域绝不会超出父视图边界；如果一次触摸命中了两个重叠视图，则兄弟视图的 Z-index 始终优先。

HitRect 和 PressRect 以及它们工作方式的示意图。

你可以使用 hitSlop 设置 HitRect，并使用 pressRetentionOffset 设置 PressRect。

信息

Pressable 使用 React Native 的 Pressability API。关于 Pressability 状态机流程及其工作方式的更多信息，请查看 Pressability 的实现。

示例​

属性​

android_disableSound
Android
​

如果为 true，则按下时不会播放 Android 系统声音。

类型默认值
booleanfalse

android_ripple
Android
​

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

类型
RippleConfig

children​

可以是子元素，也可以是一个接收布尔值的函数，该布尔值表示组件当前是否处于按下状态。

类型
React Node

unstable_pressDelay​

在按下后等待多长时间（毫秒）再调用 onPressIn。

类型
number

delayLongPress​

从 onPressIn 开始到调用 onLongPress 的持续时间（毫秒）。

类型默认值
number500

disabled​

是否禁用按压行为。

类型默认值
booleanfalse

hitSlop​

设置元素外的附加距离，在该范围内也可检测到按压。

类型
Rect or number

onHoverIn​

在悬停被激活时调用，以提供视觉反馈。

类型
({ nativeEvent: MouseEvent }) => void

onHoverOut​

在悬停被取消时调用，以撤销视觉反馈。

类型
({ nativeEvent: MouseEvent }) => void

onLongPress​

如果 onPressIn 之后的持续时间超过 500 毫秒，则调用。此时间段可通过 delayLongPress 自定义。

类型
({nativeEvent: PressEvent}) => void

onPress​

在 onPressOut 之后调用。

类型
({nativeEvent: PressEvent}) => void

onPressIn​

在触摸接触时立即调用，早于 onPressOut 和 onPress。

类型
({nativeEvent: PressEvent}) => void

onPressMove​

在按压位置移动时调用。

类型
({nativeEvent: PressEvent}) => void

onPressOut​

在触摸释放时调用。

类型
({nativeEvent: PressEvent}) => void

pressRetentionOffset​

在触发 onPressOut 之前，视图外的额外距离在该范围内的触摸仍会被视为一次按压。

类型默认值
Rect or number{bottom: 30, left: 20, right: 20, top: 20}

style​

可以是视图样式，也可以是一个接收布尔值的函数，该布尔值表示组件当前是否处于按下状态，并返回视图样式。

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

testOnly_pressed​

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

类型默认值
booleanfalse

类型定义​

RippleConfig​

android_ripple 属性的涟漪效果配置。

类型
object

属性：

名称类型必需描述
colorcolor否定义涟漪效果的颜色。
borderlessboolean否定义涟漪效果是否不包含边框。
radiusnumber否定义涟漪效果的半径。
foregroundboolean否设为 true 可将涟漪效果添加到视图前景，而不是背景。如果你的某个子视图有自己的背景，或者例如你正在显示图片且不希望涟漪被其遮挡，这将非常有用。