跳至主要內容

Pressable

Pressable 是一個核心元件包裝器，可以偵測任何已定義子元件上各種階段的按壓互動。

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

運作方式​

在由 Pressable 包裝的元素上

  • 當按壓被啟動時，會呼叫 onPressIn。
  • 當按壓手勢被停用時，會呼叫 onPressOut。

在按下 onPressIn 後，會發生以下兩種情況之一

  1. 使用者將移除他們的手指，觸發 onPressOut，然後接著觸發 onPress。
  2. 如果使用者在移除手指前，手指停留在螢幕上的時間超過 500 毫秒，則會觸發 onLongPress。（當他們移除手指時，onPressOut 仍然會觸發。）
Diagram of the onPress events in sequence.

手指並非最精確的工具，使用者經常會不小心啟動錯誤的元素或錯過啟動區域。為了協助使用者，Pressable 有一個可選的 HitRect，您可以使用它來定義觸控可以從包裝元素多遠處開始註冊。按壓可以從 HitRect 內的任何位置開始。

PressRect 允許按壓在保持啟動狀態並符合「按壓」條件的情況下，移動超出元素及其 HitRect 的範圍——想像一下，當您按下按鈕時，慢慢地將手指從按鈕上滑開。

觸控區域永遠不會超出父視圖邊界，並且如果觸控擊中兩個重疊的視圖，則兄弟視圖的 Z 索引始終優先。

Diagram of HitRect and PressRect and how they work.

您可以使用 hitSlop 設定 HitRect，並使用 pressRetentionOffset 設定 PressRect。

Pressable 使用 React Native 的 Pressability API。如需更多關於 Pressability 的狀態機流程以及其運作方式的資訊，請查看 Pressability 的實作。

範例​

Props​

android_disableSound
Android
​

如果為 true，則在按壓時不會播放 Android 系統音效。

類型預設值
booleanfalse

android_ripple
Android
​

啟用 Android ripple 效果並設定其屬性。

類型
RippleConfig

children​

子元件或接收一個布林值的函式，該布林值反映元件目前是否被按下。

類型
React 節點

unstable_pressDelay​

在按下後到呼叫 onPressIn 之間等待的持續時間（以毫秒為單位）。

類型
number

delayLongPress​

從 onPressIn 到 onLongPress 被呼叫之間的持續時間（以毫秒為單位）。

類型預設值
number500

disabled​

是否停用按壓行為。

類型預設值
booleanfalse

hitSlop​

設定元素外部的額外距離，在此距離內可以偵測到按壓。

類型
Rect 或 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

onPressOut​

當觸控被釋放時呼叫。

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

pressRetentionOffset​

在此視圖外部的額外距離，在此距離內觸控被視為按壓，然後觸發 onPressOut。

類型預設值
Rect 或 number{bottom: 30, left: 20, right: 20, top: 20}

style​

視圖樣式或接收一個布林值的函式，該布林值反映元件目前是否被按下並傳回視圖樣式。

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

testOnly_pressed​

僅用於文件或測試（例如快照測試）。

類型預設值
booleanfalse

類型定義​

RippleConfig​

android_ripple 屬性的 Ripple 效果配置。

類型
object

屬性

名稱類型必填描述
colorcolor否定義 ripple 效果的顏色。
borderlessboolean否定義 ripple 效果是否不應包含邊框。
radiusnumber否定義 ripple 效果的半徑。
foregroundboolean否設定為 true 以將 ripple 效果添加到視圖的前景，而不是背景。如果您的子視圖之一有自己的背景，或者您正在顯示圖像，並且您不希望 ripple 效果被它們覆蓋，這非常有用。