跳到主要内容

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 uses React Native's Pressability API. For more information around the state machine flow of Pressability and how it works, check out the implementation for 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​

触摸开始时立即调用,在 onPressOut 和 onPress 之前。

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 值之上。