跳到主要内容

Pressable

Pressable 是一个核心组件的封装，它可以检测到任意子组件的不同阶段的按压交互情况。

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

原理​

在被 Pressable 包装的元素上：

在按下 onPressIn 后，将会出现如下两种情况的一种：

  1. 用户移开手指，依次触发 onPressOut 和 onPress 事件。
  2. 按压持续 500 毫秒以上，触发 onLongPress 事件。（onPressOut 在移开手后依旧会触发。）
Diagram of the onPress events in sequence.

手指的精准度终究不是很精确，人们经常会不小心按错了或者错过了触发区域。为了帮助解决这个问题，Pressable 提供了一个可选项 HitRect，可以用来定义相对于包裹元素的有效触控距离。在 HitRect 内的任何地方都可以触发按压动作。

PressRect 在保持激活状态的同时，允许用户按压时在元素及设定的范围内滑动，使触控更加优雅。试想一下缓慢地滑动着离开按下的按钮。

note

触控区域不会超出绑定的父级 view，在按压到重叠的兄弟视图时，z-index 更高的那个视图会更优先。

Diagram of HitRect and PressRect and how they work.

用 hitSlop 设置 HitRect；用 pressRetentionOffset 设置 PressRect。

info

Pressable 使用了 React Native 的 Pressability API。查看 Pressability 的实现，了解更多关于 Pressability 的状态机流程和原理。

示例​

Props​

android_disableSound
Android
​

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

TypeDefault
booleanfalse

android_ripple
Android
​

使用并配置 Android 波纹效果。

Type
RippleConfig

children​

接收按压状态布尔值的子节点或函数。

Type
React Node

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 被触发前，view 额外的有效触控距离。

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

style​

可使用普通视图样式，或者一个函数来根据按压状态布尔值返回视图样式。

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

testOnly_pressed​

仅用于指导文档或测试（比如快照测试）。

TypeDefault
booleanfalse

类型定义​

RippleConfig​

android_ripple 属性的波纹效果配置。

Type
object

Properties:

NameTypeRequiredDescription
colorcolorNo定义波纹的颜色。
borderlessbooleanNo定义波纹效果是否包含边框。
radiusnumberNo定义波纹的半径。
foregroundbooleanNo设为 true 可将波纹效果添加到视图的前景而非背景。当子视图有自己的背景色或者你在显示图片时，这很有用，可以避免波纹效果被遮挡。