react-native-gesture-handler

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅最新的发布说明。

@amazon-devices/react-native-gesture-handler库是一个声明式API，向React Native公开平台原生触摸和手势系统。

React Native Gesture Handler提供原生驱动的手势管理API，用于在React Native中构建最佳的触摸型体验。

使用此库后，JavaScript响应器系统不再控制手势，而是在用户界面线程中对手势进行识别和跟踪。此库使触摸交互和手势跟踪不仅流畅，而且可靠、确定性强。

此库由系统部署，可供适用于Vega的React Native应用使用，无需单独的安装过程。此库自动链接，您的应用在运行时会链接到该库。该库保证仅与为之构建的适用于Vega的React Native版本兼容。

升级应用的适用于Vega的React Native版本时，可以考虑升级其库依赖关系的最佳实践。

有关此库及其API的更多信息，请参阅Software Mansion官方文档中的https://docs.swmansion.com/react-native-gesture-handler/docs/（仅提供英文版）。

安装

在package.json文件中添加JavaScript库依赖项。选择适用于您的React Native版本的选项卡。

React Native 0.72
React Native 0.83

已复制到剪贴板。

"dependencies": {
      ...
      "@amazon-devices/react-native-gesture-handler": "~2.0.0+2.13.0"
}

已复制到剪贴板。

"dependencies": {
      ...
      "@amazon-devices/react-native-gesture-handler": "~4.0.0+2.29.0"
}

使用npm install命令重新安装package-lock.json文件。

示例

检测单点和双击功能。

已复制到剪贴板。

import { Gesture, GestureDetector, GestureHandlerRootView } from '@amazon-devices/react-native-gesture-handler';
import React, { useEffect, useRef, useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';

export const App: React.FC = () => {
  const [message, setMessage] = useState("");
  const ref = useRef<View>(null);

  useEffect(() => {
    ref.current?.focus();
  }, [])

  const singleTap = Gesture.Tap().onStart(() => {
    setMessage("单击");
  });

  const doubleTap = Gesture.Tap().numberOfTaps(2).onStart(() => {
    setMessage("双击")
  });

  return (
    <GestureHandlerRootView style={{flex: 1}}>
      <View style={styles.container}>
        <Text>轻点该框一次或两次</Text>
        <GestureDetector gesture={Gesture.Exclusive(doubleTap, singleTap)}>
          <View style={styles.box} focusable ref={ref} />
        </GestureDetector>
        <Text>{message}</Text>
      </View>
    </GestureHandlerRootView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: 'white',
    alignItems: 'center',
    justifyContent: 'center'
  },
  box: {
    width: 200,
    height: 200,
    backgroundColor: 'plum',
    margin: 20,
  }
});

使用Pan手势处理程序移动该框。

已复制到剪贴板。

import { Gesture, GestureDetector, GestureHandlerRootView } from '@amazon-devices/react-native-gesture-handler';
import React, { useEffect, useRef, useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';

export const App: React.FC = () => {
  const [posX, setPosX] = useState(0);
  const [posY, setPosY] = useState(0);
  const ref = useRef<View>(null);

  useEffect(() => {
    ref.current?.focus();
  }, [])

  const pan = Gesture.Pan().onChange((e) => {
    setPosX((x) => x + e.changeX);
    setPosY((y) => y + e.changeY);
  })

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <View style={styles.container}>
        <Text>在屏幕上拖拽该框</Text>
        <GestureDetector gesture={pan}>
          <View style={[styles.box, { top: posY, left: posX }]} focusable ref={ref} />
        </GestureDetector>
      </View>
    </GestureHandlerRootView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: 'white',
    alignItems: 'center',
    justifyContent: 'center'
  },
  box: {
    width: 200,
    height: 200,
    backgroundColor: 'plum',
    margin: 20,
  }
});

支持的API

Vega上的手势处理程序库提供了对官方文档中列出的所有手势类型和原生组件的支持。

手势类型

手势类型	描述
平移	一种连续的手势处理程序，可以识别平移（拖动）手势并跟踪其移动。
点击	一种离散的手势处理程序，可识别一次或多次点击。
长按	一种离散的手势处理程序，当按下相应视图足够长的时间时会激活。
旋转	一种连续的手势处理程序，可以识别旋转手势并跟踪其移动。
捏合	一种连续的手势处理程序，可识别捏合手势。此处理程序支持跟踪两根手指之间的距离，并使用该信息来缩放内容。
快速滑动	一种离散的手势处理程序，当动作距离足够长和足够快时就会激活。
手动	一种没有特定激活标准或事件数据集的简单手势。应用开发者必须使用手势状态管理器在其应用逻辑中以编程方式处理状态。

原生组件

原生组件	描述
RNGestureHandlerButton	手势处理程序库提供可以充当按钮的原生组件。这些组件可以作为RN核心中`TouchableHighlight`或`TouchableOpacity`的替代者。

支持的版本

NPM程序包版本	Vega SDK版本	Vega OS版本	React Native版本
~2.0.x+2.13.0	0.23及更早版本	`操作系统1.1 (1401010009820)`及更早版本	0.72
~4.0.0+2.29.0	0.24	`操作系统1.2 (2101020054720)`	0.72、0.83

其他资源

有关更多库的信息，请参阅支持的第三方库和服务。

Last updated: 2026年7月21日