React Native Gesture Handler 使用教程

2026-01-16 09:23:29作者：侯霆垣

项目介绍

React Native Gesture Handler 是一个提供原生驱动的触摸和手势管理API的库，旨在为React Native构建最佳的基于触摸的体验。该库由Software Mansion开发，自2012年以来，Software Mansion一直是一家专注于构建Web和移动应用的软件机构。React Native Gesture Handler 通过声明式API暴露了平台的原生触摸和手势系统，使得手势不再由JavaScript响应系统控制，而是在UI线程中识别和跟踪。

项目快速启动

安装

首先，确保你已经安装了React Native CLI。然后，通过以下命令安装 react-native-gesture-handler：

npm install react-native-gesture-handler
# 或者使用 yarn
yarn add react-native-gesture-handler

链接

对于React Native 0.60及以上版本，自动链接会处理依赖关系。对于旧版本，需要手动链接：

react-native link react-native-gesture-handler

初始化

在你的应用入口文件（通常是 index.js 或 App.js）中，导入并初始化 react-native-gesture-handler：

import 'react-native-gesture-handler';
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';

const Stack = createStackNavigator();

const App = () => {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Details" component={DetailsScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
};

export default App;

应用案例和最佳实践

基本手势识别

使用 TapGestureHandler 实现一个简单的点击手势：

import React from 'react';
import { TapGestureHandler, State } from 'react-native-gesture-handler';
import { View, Text } from 'react-native';

const TapExample = () => {
  const onHandlerStateChange = event => {
    if (event.nativeEvent.state === State.END) {
      alert('Tap!');
    }
  };

  return (
    <TapGestureHandler onHandlerStateChange={onHandlerStateChange}>
      <View style={{ width: 100, height: 100, backgroundColor: 'blue' }}>
        <Text style={{ color: 'white' }}>Tap Me</Text>
      </View>
    </TapGestureHandler>
  );
};

export default TapExample;

滑动菜单

结合 PanGestureHandler 和 Animated 实现一个滑动菜单：

import React, { useRef } from 'react';
import { PanGestureHandler, State } from 'react-native-gesture-handler';
import { Animated, View, StyleSheet } from 'react-native';

const SwipeMenu = () => {
  const translationX = useRef(new Animated.Value(0)).current;

  const onGestureEvent = Animated.event(
    [{ nativeEvent: { translationX } }],
    { useNativeDriver: true }
  );

  const onHandlerStateChange = event => {
    if (event.nativeEvent.state === State.END) {
      Animated.spring(translationX, {
        toValue: 0,
        useNativeDriver: true,
      }).start();
    }
  };

  return (
    <PanGestureHandler
      onGestureEvent={onGestureEvent}
      onHandlerStateChange={onHandlerStateChange}>
      <Animated.View style={[styles.menu, { transform: [{ translateX: translationX }] }]} />
    </PanGestureHandler>
  );
};

const styles = StyleSheet.create({
  menu: {
    width: 200,
    height: '100%',
    backgroundColor: 'red',
  },
});

export default SwipeMenu;