Expo 触觉 iconExpo 触觉

一个提供访问 Android 系统振动效果、iOS 触觉引擎以及 Web 上 Web 振动 API 的库。

Android
iOS
Web
Bundled version:
~14.1.4

expo-haptics 提供触觉(触摸)反馈:

¥expo-haptics provides haptic (touch) feedback for:

  • 使用 Vibrator 系统服务的 Android 设备。

    ¥Android devices using Vibrator system service.

  • 使用 Taptic Engine 的 iOS 10+ 设备。

    ¥iOS 10+ devices using the Taptic Engine.

  • Web 平台使用 Web Vibration API。

    ¥Web platforms using the Web Vibration API.

在 iOS 上,如果用户设备上满足以下任一条件,Taptic 引擎将不执行任何操作:

¥On iOS, the Taptic engine will do nothing if any of the following conditions are true on a user's device:

  • 低功耗模式已启用。这可以用 expo-battery 检测到。

    ¥Low Power Mode is enabled. This can be detected with expo-battery.

  • 用户在设置中禁用了 Taptic Engine。

    ¥User disabled the Taptic Engine in settings.

  • iOS 相机处于活动状态(以防止不稳定)。

    ¥iOS Camera is active (to prevent destabilization).

  • iOS 听写处于活动状态(不会干扰麦克风输入)。

    ¥iOS dictation is active (to not disturb the microphone input).

在网页端,该库使用 Web Vibration API。注意以下几点:

¥On web, the library uses the Web Vibration API. Note the following:

  • 浏览器必须支持该 API(请检查 浏览器兼容性

    ¥The API must be supported by the browser (check browser compatibility)

  • 设备必须配备振动硬件

    ¥The device must have vibration hardware

  • 用户必须授予使用振动(通常是自动)的权限。

    ¥The user must grant permission to use vibration (usually automatic)

  • 某些浏览器可能会在某些情况下忽略振动(例如,后台标签页)。

    ¥Some browsers may ignore vibration in certain contexts (for example, background tabs)

安装

¥Installation

Terminal
npx expo install expo-haptics

If you are installing this in an existing React Native app, make sure to install expo in your project.

配置

¥Configuration

在 Android 上,此库需要控制设备振动的权限。VIBRATE 权限会自动添加。

¥On Android, this library requires permission to control vibration on the device. The VIBRATE permission is added automatically.

用法

¥Usage

Haptics usage
import { StyleSheet, View, Text, Button } from 'react-native';
import * as Haptics from 'expo-haptics';

export default function App() {
return (
  <View style={styles.container}>
    <Text style={styles.text}>Haptics.selectionAsync</Text>
    <View style={styles.buttonContainer}>
      <Button title="Selection" onPress={() => Haptics.selectionAsync()} />
    </View>
    <Text style={styles.text}>Haptics.notificationAsync</Text>
    <View style={styles.buttonContainer}>
      <Button
        title="Success"
        onPress={
          () =>
            Haptics.notificationAsync(
              Haptics.NotificationFeedbackType.Success
            )
        }
      />
      <Button
        title="Error"
        onPress={
          () =>
            Haptics.notificationAsync(
              Haptics.NotificationFeedbackType.Error
            )
        }
      />
      <Button
        title="Warning"
        onPress={
          () =>
            Haptics.notificationAsync(
              Haptics.NotificationFeedbackType.Warning
            )
        }
      />
    </View>
    <Text style={styles.text}>Haptics.impactAsync</Text>
    <View style={styles.buttonContainer}>
      <Button
        title="Light"
        onPress={
          () => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)
        }
      />
      <Button
        title="Medium"
        onPress={
          () => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium)
        }
      />
      <Button
        title="Heavy"
        onPress={
          () => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Heavy)
        }
      />
      <Button
        title="Rigid"
        onPress={
          () => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Rigid)
        }
      />
      <Button
        title="Soft"
        onPress={
          () => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Soft)
        }
      />
    </View>
  </View>
);
}

const styles = StyleSheet.create({
container: {
  flex: 1,
  justifyContent: 'center',
  paddingHorizontal: 16,
},
buttonContainer: {
  flexDirection: 'row',
  alignItems: 'stretch',
  marginTop: 10,
  marginBottom: 30,
  justifyContent: 'space-between',
},
});

API

import * as Haptics from 'expo-haptics';

Methods

Haptics.impactAsync(style)

ParameterTypeDescription
style(optional)ImpactFeedbackStyle

A collision indicator that on Android is simulated using Vibrator and on iOS, it is directly mapped to UIImpactFeedbackStyle. You can use one of Haptics.ImpactFeedbackStyle.{Light, Medium, Heavy, Rigid, Soft}.

Default:ImpactFeedbackStyle.Medium

Returns:
Promise<void>

A Promise which fulfils once native size haptics functionality is triggered.

Haptics.notificationAsync(type)

ParameterTypeDescription
type(optional)NotificationFeedbackType

A notification feedback type that on Android is simulated using Vibrator and iOS is directly mapped to UINotificationFeedbackType. You can use one of Haptics.NotificationFeedbackType.{Success, Warning, Error}.

Default:NotificationFeedbackType.Success

The kind of notification response used in the feedback.

Returns:
Promise<void>

A Promise which fulfils once native size haptics functionality is triggered.

Haptics.performAndroidHapticsAsync(type)

Only for:
Android

ParameterType
typeAndroidHaptics

Use the device haptics engine to provide physical feedback to the user.

Returns:
Promise<void>

Haptics.selectionAsync()

Used to let a user know when a selection change has been registered.

Returns:
Promise<void>

A Promise which fulfils once native size haptics functionality is triggered.

Enums

AndroidHaptics

Only for:
Android

Clock_Tick

AndroidHaptics.Clock_Tick = "clock-tick"

The user has pressed either an hour or minute tick of a Clock.

Confirm

AndroidHaptics.Confirm = "confirm"

A haptic effect to signal the confirmation or successful completion of a user interaction.

Context_Click

AndroidHaptics.Context_Click = "context-click"

The user has performed a context click on an object.

Drag_Start

AndroidHaptics.Drag_Start = "drag-start"

The user has started a drag-and-drop gesture. The drag target has just been "picked up".

Gesture_End

AndroidHaptics.Gesture_End = "gesture-end"

The user has finished a gesture (for example, on the soft keyboard).

Gesture_Start

AndroidHaptics.Gesture_Start = "gesture-start"

The user has started a gesture (for example, on the soft keyboard).

Keyboard_Press

AndroidHaptics.Keyboard_Press = "keyboard-press"

The user has pressed a virtual or software keyboard key.

Keyboard_Release

AndroidHaptics.Keyboard_Release = "keyboard-release"

The user has released a virtual keyboard key.

Keyboard_Tap

AndroidHaptics.Keyboard_Tap = "keyboard-tap"

The user has pressed a soft keyboard key.

Long_Press

AndroidHaptics.Long_Press = "long-press"

The user has performed a long press on an object that results in an action being performed.

No_Haptics

AndroidHaptics.No_Haptics = "no-haptics"

No haptic feedback should be performed.

Reject

AndroidHaptics.Reject = "reject"

A haptic effect to signal the rejection or failure of a user interaction.

Segment_Frequent_Tick

AndroidHaptics.Segment_Frequent_Tick = "segment-frequent-tick"

The user is switching between a series of many potential choices. For example, minutes on a clock face or individual percentages. This constant is expected to be very soft, so as not to be uncomfortable when performed a lot in quick succession. If the device can't make a suitably soft vibration, then it may not make any vibration.

Segment_Tick

AndroidHaptics.Segment_Tick = "segment-tick"

The user is switching between a series of potential choices. For example, items in a list or discrete points on a slider.

Text_Handle_Move

AndroidHaptics.Text_Handle_Move = "text-handle-move"

The user has performed a selection/insertion handle move on text field.

Toggle_Off

AndroidHaptics.Toggle_Off = "toggle-off"

The user has toggled a switch or button into the off position.

Toggle_On

AndroidHaptics.Toggle_On = "toggle-on"

The user has toggled a switch or button into the on position.

Virtual_Key

AndroidHaptics.Virtual_Key = "virtual-key"

The user has pressed on a virtual on-screen key.

Virtual_Key_Release

AndroidHaptics.Virtual_Key_Release = "virtual-key-release"

The user has released a virtual key.

ImpactFeedbackStyle

The mass of the objects in the collision simulated by a UIImpactFeedbackGenerator object UINotificationFeedbackStyle.

Heavy

ImpactFeedbackStyle.Heavy = "heavy"

A collision between large, heavy user interface elements.

Light

ImpactFeedbackStyle.Light = "light"

A collision between small, light user interface elements.

Medium

ImpactFeedbackStyle.Medium = "medium"

A collision between moderately sized user interface elements.

Rigid

ImpactFeedbackStyle.Rigid = "rigid"

A collision between user interface elements that are rigid, exhibiting a small amount of compression or elasticity.

Soft

ImpactFeedbackStyle.Soft = "soft"

A collision between user interface elements that are soft, exhibiting a large amount of compression or elasticity.

NotificationFeedbackType

The type of notification feedback generated by a UINotificationFeedbackGenerator object. UINotificationFeedbackType.

Error

NotificationFeedbackType.Error = "error"

A notification feedback type indicating that a task has failed.

Success

NotificationFeedbackType.Success = "success"

A notification feedback type indicating that a task has completed successfully.

Warning

NotificationFeedbackType.Warning = "warning"

A notification feedback type indicating that a task has produced a warning.