文档模板：v0.4.2

react-native-gesture-handler

本项目基于 react-native-gesture-handler 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-gesture-handler 版本所属关系如下：

三方库名称	三方库版本（npm地址）	发布信息	支持RN版本	Autolink	编译API版本	社区基线版本	源码地址
@react-native-ohos/react-native-gesture-handler	2.23.2	Gitcode Releases	0.77.*	否	API12+	2.25.0	br_rnoh0.77

简介

React Native Gesture Handler 为 React Native 提供了原生手势处理能力，支持多种手势类型（如点击、拖拽、捏合、旋转等），并提供 Touchable 组件和手势检测器（GestureDetector），实现流畅的手势交互体验。

下载安装

请到三方库的 Releases 发布地址查看配套的版本信息：@react-native-ohos/react-native-gesture-handler Releases。对于未发布到npm的旧版本，请参考安装指南安装tgz包。

进入到工程目录并输入以下命令：

npm

npm install @react-native-ohos/react-native-gesture-handler

yarn

yarn add @react-native-ohos/react-native-gesture-handler

import React, { Component } from "react";
import { Animated, Dimensions } from "react-native";
import {
  GestureHandlerRootView,
  PanGestureHandler,
} from "react-native-gesture-handler";

const { width } = Dimensions.get("screen");
const circleRadius = 30;

class Circle extends Component {
  _touchX = new Animated.Value(width / 2 - circleRadius);

  _onPanGestureEvent = Animated.event([{ nativeEvent: { x: this._touchX } }], {
    useNativeDriver: true,
  });

  render() {
    return (
      <GestureHandlerRootView>
        <PanGestureHandler onGestureEvent={this._onPanGestureEvent}>
          <Animated.View
            style={{
              height: 150,
              justifyContent: "center",
            }}
          >
            <Animated.View
              style={[
                {
                  backgroundColor: "#42a5f5",
                  borderRadius: circleRadius,
                  height: circleRadius * 2,
                  width: circleRadius * 2,
                },
                {
                  transform: [
                    {
                      translateX: Animated.add(
                        this._touchX,
                        new Animated.Value(-circleRadius)
                      ),
                    },
                  ],
                },
              ]}
            />
          </Animated.View>
        </PanGestureHandler>
      </GestureHandlerRootView>
    );
  }
}

export default function App() {
  return <Circle />;
}

Link

	是否支持autolink	RN框架版本
2.23.2	No	0.77

使用AutoLink的工程需要根据该文档配置，Autolink框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过ManualLink配置。

ManualLink: 此步骤为手动配置原生依赖项的指导

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony

1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

{
  ...
  "overrides": {
    "@rnoh/react-native-openharmony" : "./react_native_openharmony"
  }
}

2. 引入原生端代码

"properties":{
  "ohos.nativeResolver":false
}

目前有两种方法：

1. 通过 har 包引入；
2. 直接链接源码。

方法一：通过 har 包引入（推荐）

打开 entry/oh-package.json5，添加以下依赖

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",

    "@react-native-ohos/react-native-gesture-handler": "file:../../node_modules/@react-native-ohos/react-native-gesture-handler/harmony/gesture_handler.har"
  }

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

方法二：直接链接源码

3. 配置 CMakeLists 和引入 GestureHandlerPackage

打开 entry/src/main/cpp/CMakeLists.txt，添加：

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+ set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-gesture-handler/src/main/cpp" ./gesture-handler)
# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)
target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_gesture_handler)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
+ #include "generated/RNOHGeneratedPackage.h"
+ #include "GestureHandlerPackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
+     std::make_shared<RNOHGeneratedPackage>(ctx),
+     std::make_shared<GestureHandlerPackage>(ctx)
    };
}

4. 在 ArkTs 侧引入 Gesture Handler Package

打开 entry/src/main/ets/RNPackagesFactory.ts，添加：

+ import GestureHandlerPackage from '@react-native-ohos/react-native-gesture-handler';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new SamplePackage(ctx),
+   new GestureHandlerPackage(ctx),
  ];
}

运行

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下版本验证通过：

1. RNOH：0.77.*; SDK：HarmonyOS 5.1.0.150 (API Version 12); IDE：DevEco Studio 5.1.1.830; ROM：5.1.0.150;

编译运行API要求（如有）

使用示例

下面的代码展示了这个库的基本使用场景：

Gestures

Gesture detector

GestureDetector 是 Gesture Handler 库 2.x 版本的一个主要组件。

Gesture detector 属性

Name	Description	Type	Required	Platform	HarmonyOS Support
gesture	一个包含配置与回调的手势对象。	base gestures or any ComposedGesture	yes	All	yes

Gesture 的方法

method	Description	Type	Platform	HarmonyOS Support
Gesture.Tap()	使用默认配置且无回调创建一个 TapGesture 实例。	function()	All	yes
Gesture.Pan()	使用默认配置且无回调创建一个 PanGesture 实例。	function()	All	yes
Gesture.Rotation()	使用默认配置且无回调创建一个 RotationGesture 实例。	function()	All	yes
Gesture.LongPress()	使用默认配置且无回调创建一个 LongPressGesture 实例。	function()	All	yes
Gesture.Manual()	使用默认配置且无回调创建一个 ManualGesture 实例。	function()	All	yes
Gesture.Pinch()	使用默认配置且无回调创建一个 PinchGesture 实例。	function()	All	yes
Gesture.Fling()	使用默认配置且无回调创建一个 FlingGesture 实例。	function()	All	yes

Components

Touchables

Gesture Handler 库提供了一种基于原生按钮的 React Native touchable 组件的实现，它不依赖于 React Native 的 JS responder system。这些组件的实现遵循相同的 API，旨在替代 React Native 中的 touchable 组件,HarmonyOS 已全面支持。

• Touchable Opacity
• Touchable Without Feedback
• Touchable Highlight
• Touchable Native Feedback

Buttons

BaseButton 属性

Name	Description	Type	Platform	HarmonyOS Support
onActiveStateChange	当按钮从非激活切换到激活或反向切换时触发。	function	All	yes
onPress	按钮被按下时触发。	function	All	yes
onLongPress	按钮按住至少 delayLongPress 毫秒后触发。	function	All	yes
exclusive	是否允许多个按钮同时被按下，默认值为 true。	boolean	All	yes
delayLongPress	触发 onLongPress 前的延迟（毫秒），默认 600。	number	All	yes

ReactButton 属性

Name	Description	Type	Platform	HarmonyOS Support
underlayColor	按钮处于激活态时会被调暗的背景色。	Color	All	yes

Drawer Layout

属性

Name	Description	Type	Platform	HarmonyOS Support
drawerType	抽屉的展示类型。	'front'|'back'|'slide'	All	yes
edgewidth	定义手势距离内容视图边缘多远时才会被激活。	number	All	yes
hideStatusBar	设为 true 时，抽屉被拉出或处于打开状态会通过 StatusBar API 隐藏系统状态栏。	boolean	All	yes
statusbaranimation	在 hideStatusBar 为 true 时，选择隐藏/显示状态栏使用的动画。	'fade'|'slide'|'none'	All	no
overlaycolor	抽屉打开时覆盖在内容视图之上的半透明遮罩颜色。	color	All	yes
rendernavigationview	标准实现中已包含的必填参数，用于渲染导航视图。	function	All	yes
ondrawerclose	抽屉关闭时调用。	function	All	yes
ondraweropen	抽屉打开时调用。	function	All	yes
ondrawerslide	抽屉因触摸事件滑动打开时调用。	function	All	yes
ondrawerstatechanged	抽屉状态变化时调用。	function	All	yes
children	默认渲染并被抽屉包裹的子组件。	component| function	All	yes

Swipeable

属性

Name	Description	Type	Platform	HarmonyOS Support
friction	视觉交互相对手势距离的延滞程度。	number	All	yes
leftThreshold	释放面板后，从左侧到达该距离就会动画到打开状态。	number	All	yes
rightThreshold	释放面板后，从右侧到达该距离就会动画到打开状态。	number	All	yes
dragOffsetFromLeftEdge	从左边缘开始拖动到被视为滑动所需的距离。	number	All	yes
dragOffsetFromRightEdge	从右边缘开始拖动到被视为滑动所需的距离。	number	All	yes
overshootLeft	是否允许可滑动面板被拉出超过左侧动作面板宽度。	boolean	All	yes
overshootRight	是否允许可滑动面板被拉出超过右侧动作面板宽度。	boolean	All	yes
overshootFriction	超出范围时视觉交互相对手势距离的延滞程度。	number	All	yes
onSwipeableOpen	动作面板打开时调用。	function(direction: 'left' | 'right', swipeable: Swipeable)	All	yes
onSwipeableClose	动作面板关闭时调用。	function(direction: 'left' | 'right', swipeable: Swipeable)	All	yes
onSwipeableWillOpen	动作面板开始动画打开（左/右）时调用。	function((direction: 'left' | 'right'))	All	yes
onSwipeableWillClose	动作面板开始动画关闭时调用。	function((direction: 'left' | 'right'))	All	yes
renderLeftActions	用于返回左侧动作面板的渲染方法，提供的插值输入区间可用于额外动画。	function(progressAnimatedValue: AnimatedInterpolation, dragAnimatedValue: AnimatedInterpolation, swipeable: Swipeable)	All	yes
renderRightActions	用于返回右侧动作面板的渲染方法（向左滑动时显露）。	function(progressAnimatedValue: AnimatedInterpolation, dragAnimatedValue: AnimatedInterpolation, swipeable: Swipeable)	All	yes
containerStyle	容器（Animated.View）的样式对象，例如覆盖 overflow: 'hidden'。	StyleProp	All	yes
childrenContainerStyle	子容器（Animated.View）的样式对象，例如应用 flex: 1。	StyleProp	All	yes

Gesture handlers(legacy)

Gesture handlers 通用属性

NAME	Description	TYPE	Required	Platform	HarmonyOS Support
enabled	指定该手势处理器是否应当分析触摸事件流。	boolean	no	All	yes
hitSlop	控制可用来开始识别手势的视图区域范围。	object	no	All	yes
onGestureEvent	当处理器处于 ACTIVE 状态时，对后续触摸事件逐个触发的回调。	callback	no	All	yes
onHandlerStateChange	当处理器状态变化时触发的回调。	callback	no	All	yes

Gesture handlers 通用事件数据

以下是提供给 onGestureEvent 和 onHandlerStateChange 回调的通用事件数据:

NAME	Description	TYPE	Platform	HarmonyOS Support
state	处理器的当前状态。	State	All	yes
numberOfPointers	当前放在屏幕上的指针（手指）数量。	number	All	yes

PanGestureHandler

PanGestureHandler 属性

NAME	Description	TYPE	Required	Platform	HarmonyOS Support
minDist	手指（或多指）需要移动的最小距离，超过后处理器才会激活。	number	no	All	yes
minPointers	处理器激活前需要放置的最少手指数量。	number	no	All	yes
maxPointers	当屏幕上放置到指定数量的手指且尚未激活时，将停止识别该手势。	number	no	All	yes
activeOffsetX	X 轴方向（点单位）内，不会触发处理器激活的移动区间。	number	no	All	yes
activeOffsetY	Y 轴方向（点单位）内，不会触发处理器激活的移动区间。	number	no	All	yes

PanGestureHandler 事件数据

请到查看基础 handler 类的通用事件数据。以下是 PanGestureHandler 特有的事件数据。

translationX

手势过程中沿 X 轴累计的平移距离，单位为 point。

translationY

手势过程中沿 Y 轴累计的平移距离，单位为 point。

velocityX

当前沿 X 轴的平移速度，单位为 point/s。

velocityY

当前沿 Y 轴的平移速度，单位为 point/s。

x

指针（单指或多指的主指）相对于附加到处理器的视图的当前 X 坐标，单位为 point。

y

指针（单指或多指的主指）相对于附加到处理器的视图的当前 Y 坐标，单位为 point。

TapGestureHandler

TapGestureHandler 属性

NAME	Description	TYPE	Required	Platform	HarmonyOS Support
minPointers	处理器激活前需要放置的最少手指数量。	number	no	All	yes
maxDurationMs	手指触摸后必须在多快时间内抬起的最大时长（毫秒）。	number	no	All	yes
maxDelayMs	在需要多次点击时，两次点击之间允许经过的最大时间（毫秒）。	number	no	All	yes
maxDeltaX	点击手势期间手指在 X 轴允许移动的最大距离（point）。	number	no	All	yes
maxDeltaY	点击手势期间手指在 Y 轴允许移动的最大距离（point）。	number	no	All	yes
maxDist	点击手势期间手指允许移动的最大距离（point）。	number	no	All	yes

TapGestureHandler 事件数据

请到查看基础 handler 类的通用事件数据。以下是 TapGestureHandler 特有的事件数据。

x

指针（单指或多指的主指）相对于附加到处理器的视图的当前 X 坐标，单位为 point。

y

指针（单指或多指的主指）相对于附加到处理器的视图的当前 Y 坐标，单位为 point。

absoluteX

指针（单指或多指的主指）相对于窗口的当前 X 坐标，单位为 point。若手势会导致视图变换，推荐使用 absoluteX 而不是 x。

absoluteY

指针（单指或多指的主指）相对于窗口的当前 Y 坐标，单位为 point。若手势会导致视图变换，推荐使用 absoluteY 而不是 y。

遗留问题

• statusbaranimation属性由于Arkts bar 只有淡出淡入动画和RN框架状态栏动画不支持，该功能暂不支持，问题: issue#55
• 0.82上游社区升级遗留问题，问题: issue#39

其他

• 当使用框架 release 包时（react_native_openharmony_release.har），因为手势库用到了 deviceinfo 接口，需要在工程的 cmake 配置导入libdeviceinfo_ndk.z.so

# CMakeLists.txt
target_link_libraries(cpplib PUBLIC libace_napi.z.so 
+ libdeviceinfo_ndk.z.so)

目录结构

/rntpc_react-native-gesture-handler  # 项目根目录
├── harmony              # 鸿蒙适配代码
│    └─ gesture_handler.har          # har包
│    └─ gesture_handler                  # 鸿蒙适配核心代码
│          └─ index.ets    # 鸿蒙适配代码入口    
│          └─ src/main/ets  
│              └─ RNOHGestureHandler  # GestureHandler组件   
├── src                  # RN代码
│    └─ index.ts  # 入口文件 
│    └─ gestures  # 手势定义          
├── README.md           # 中文安装使用方法    
├── README_en.md   # 英文安装使用方法                    

贡献代码

使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR 。

开源协议

本项目基于 The MIT License (MIT) ，请自由地享受和参与开源。