跳到主要内容

Pressable

Pressable 是一个 Core Component 包装器,可以检测其定义的任意子组件上的各种按压交互阶段。

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

工作原理

在由 Pressable 包装的元素上:

在按下 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 的实现。

示例

Props

android_disableSound
Android

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

TypeDefault
booleanfalse

android_ripple
Android

启用 Android 波纹效果并配置其属性。color 字段同时接受普通颜色和 PlatformColor 值,因此你可以引用 ?attr/colorAccent 等主题属性。使用 PlatformColor 时,当系统配置发生变化(例如在浅色模式和深色模式之间切换)时,波纹会自动更新。

children

可以是子元素,也可以是一个接收布尔值的函数,该布尔值反映组件当前是否处于按压状态。

unstable_pressDelay

按下后到调用 onPressIn 之前等待的时长(以毫秒为单位)。

Type
number

delayLongPress

onPressIn 开始到调用 onLongPress 之前的时长(以毫秒为单位)。

TypeDefault
number500

disabled

是否禁用按压行为。

TypeDefault
booleanfalse

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

触摸开始时立即调用,在 onPressOutonPress 之前。

Type
({nativeEvent: PressEvent}) => void

onPressMove

按压位置移动时调用。

Type
({nativeEvent: PressEvent}) => void

onPressOut

触摸释放时调用。

Type
({nativeEvent: PressEvent}) => void

pressRetentionOffset

在触发 onPressOut 之前,触摸被视为按压时视图外部的额外距离。

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

style

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

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

testOnly_pressed

仅用于文档或测试(例如快照测试)。

TypeDefault
booleanfalse

类型定义

RippleConfig

android_ripple 属性的波纹效果配置。

Type
object

属性:

NameTypeRequiredDescription
colorcolor or PlatformColorNo定义波纹效果的颜色。
borderlessbooleanNo定义波纹效果是否不包含边框。
radiusnumberNo定义波纹效果的半径。
foregroundbooleanNo设置为 true 可将波纹效果添加到视图的前景,而不是背景。 如果子视图之一有自己的背景,或者例如正在显示图像,并且你不希望波纹被它们覆盖,这会很有用。
alphanumberNo控制波纹的不透明度。接受 0.0(完全透明)到 1.0(完全不透明)之间的值。该值会叠加在颜色中已有的 alpha 值之上。