模板版本：v0.2.2

@ohmi/react-native-gesture-handler

[!TIp] Git 地址

介绍

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

安装与使用

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

npm

1npm install @ohmi/react-native-gesture-handler

yarn

1yarn add @ohmi/react-native-gesture-handler

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

[!WARNING] 使用时 import 的库名不变。

1import React, { Component } from "react";
2import { Animated, Dimensions } from "react-native";
3import {
4  GestureHandlerRootView,
5  PanGestureHandler,
6} from "react-native-gesture-handler";
7
8const { width } = Dimensions.get("screen");
9const circleRadius = 30;
10
11class Circle extends Component {
12  _touchX = new Animated.Value(width / 2 - circleRadius);
13
14  _onPanGestureEvent = Animated.event([{ nativeEvent: { x: this._touchX } }], {
15    useNativeDriver: true,
16  });
17
18  render() {
19    return (
20      <GestureHandlerRootView>
21        <PanGestureHandler onGestureEvent={this._onPanGestureEvent}>
22          <Animated.View
23            style={{
24              height: 150,
25              justifyContent: "center",
26            }}
27          >
28            <Animated.View
29              style={[
30                {
31                  backgroundColor: "#42a5f5",
32                  borderRadius: circleRadius,
33                  height: circleRadius * 2,
34                  width: circleRadius * 2,
35                },
36                {
37                  transform: [
38                    {
39                      translateX: Animated.add(
40                        this._touchX,
41                        new Animated.Value(-circleRadius)
42                      ),
43                    },
44                  ],
45                },
46              ]}
47            />
48          </Animated.View>
49        </PanGestureHandler>
50      </GestureHandlerRootView>
51    );
52  }
53}
54
55export default function App() {
56  return <Circle />;
57}

使用Codegen

本库未带rc.x的版本号是已经适配了 Codegen ，在使用前需要主动执行生成三方库桥接代码，详细请参考 Codegen 使用文档。

Link

目前 HarmonyOS 暂不支持 AutoLink，所以 Link 步骤需要手动配置。

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

1.在工程根目录的 oh-package.json5 添加 overrides 字段

1{
2  ...
3  "overrides": {
4    "@rnoh/react-native-openharmony" : "./react_native_openharmony"
5  }
6}

2.引入原生端代码

[!TIP] 引入原生代码之前请确认IDE版本，5.0.3.810及其之后的版本需要在harmony工程中的hvigor-config.json5文件中新增如下配置以解决路径过长导致的编译报错问题 "properties":{ "ohos.nativeResolver":false }

目前有两种方法：

1. 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
2. 直接链接源码。

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

[!TIP] har 包位于三方库安装路径的 harmony 文件夹下。

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

1"dependencies": {
2    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
3
4    "@ohmi/react-native-gesture-handler": "file:../../node_modules/@ohmi/react-native-gesture-handler/harmony/gesture_handler.har"
5  }

点击右上角的 sync 按钮

或者在终端执行：

1cd entry
2ohpm install

方法二：直接链接源码

[!TIP] 如需使用直接链接源码，请参考直接链接源码说明

3.配置 CMakeLists 和引入 GestureHandlerPackage

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

1project(rnapp)
2cmake_minimum_required(VERSION 3.4.1)
3set(CMAKE_SKIP_BUILD_RPATH TRUE)
4set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
5set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
6+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
7set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
8set(LOG_VERBOSITY_LEVEL 1)
9set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
10set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
11set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
12add_compile_definitions(WITH_HITRACE_SYSTRACE)
13
14add_subdirectory("${RNOH_CPP_DIR}" ./rn)
15
16# RNOH_BEGIN: manual_package_linking_1
17add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
18+ add_subdirectory("${OH_MODULES}/@ohmi/react-native-gesture-handler/src/main/cpp" ./gesture-handler)
19# RNOH_END: manual_package_linking_1
20
21file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")
22
23add_library(rnoh_app SHARED
24    ${GENERATED_CPP_FILES}
25    "./PackageProvider.cpp"
26    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
27)
28target_link_libraries(rnoh_app PUBLIC rnoh)
29
30# RNOH_BEGIN: manual_package_linking_2
31target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
32+ target_link_libraries(rnoh_app PUBLIC rnoh_gesture_handler)
33# RNOH_END: manual_package_linking_2

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

1#include "RNOH/PackageProvider.h"
2+ #include "generated/RNOHGeneratedPackage.h"
3+ #include "GestureHandlerPackage.h"
4
5using namespace rnoh;
6
7std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
8    return {
9+     std::make_shared<RNOHGeneratedPackage>(ctx),
10+     std::make_shared<GestureHandlerPackage>(ctx)
11    };
12}

4.在 ArkTs 侧引入 Gesture Handler Package

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

1+ import { GestureHandlerPackage } from '@ohmi/react-native-gesture-handler/ts';
2
3export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
4  return [
5    new SamplePackage(ctx),
6+   new GestureHandlerPackage(ctx),
7  ];
8}

5.运行

点击右上角的 sync 按钮

或者在终端执行：

1cd entry
2ohpm install

在vscode终端运行 npm run codegen

然后编译、运行即可。

约束与限制

4.API reference

4.1 Components

4.1.1 Touchables

• Touchable Opacity
• Touchable Without Feedback
• Touchable Highlight

4.1.2 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	安卓和鸿蒙都未生效
delayLongPress	定义触发 onLongPress 回调的延迟时间，单位为毫秒。默认值为 600	number	All	yes

ReactButton 属性

Name	Description	Type	Platform	HarmonyOS Support
underlayColor	这是当按钮处于活动状态时将变暗的背景颜色	Color	All	yes

4.1.3 Drawer Layout

属性

Name	Description	Type	Platform	HarmonyOS Support
drawerType	一个手势对象	'front'|'back'|'slide'	All	yes
edgewidth	允许定义手势在内容视图边缘多远处被激活	number	All	yes
hideStatusBar	当设置为 true 时，Drawer 组件会在抽屉被拉出或处于“打开”状态时使用状态栏 API 隐藏操作系统状态栏	boolean	All	yes
statusbaranimation	当 hideStatusBar 设置为 true 时使用，用于选择隐藏/显示状态栏时使用的动画	'fade'|'slide'|'none'	All	安卓和鸿蒙设置三种Type后均为一种效果
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	Children 是默认渲染的组件，被抽屉组件包裹	component| function	All	yes

4.1.4 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	这个映射描述了用于额外插值的 inputRange 的值：AnimatedValue: [startValue, endValue]	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

4.2 Gesture handlers

4.2.1 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

4.2.2 Gesture handlers 通用事件数据

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

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

4.2.3 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 事件数据

translationX

沿X轴方向的平移手势在手势持续时间内累积的位移值。该值以点为单位表示。

translationY

沿Y轴方向的平移手势在手势持续时间内累积的位移值。该值以点为单位表示。

velocityX

当前时刻沿X轴方向的平移手势的速度。该值以每秒点数为单位表示。

velocityY

当前时刻沿Y轴方向的平移手势的速度。该值以每秒点数为单位表示。

x

当前指针（手指或在有多根手指时的主指针）相对于绑定到处理器的视图的X坐标。以点为单位表示。

y

当前指针（手指或在有多根手指时的主指针）相对于绑定到处理器的视图的Y坐标。以点为单位表示。

4.2.4 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轴方向允许移动的最大范围	number	no	All	yes
maxDeltaY	以点为单位表示的最大距离，定义了在点击手势过程中，手指沿Y轴方向允许移动的最大范围	number	no	All	yes
maxDist	以点为单位表示的最大距离，定义了在点击手势过程中，手指允许移动的最大范围（综合X轴和Y轴）	number	no	All	yes

TapGestureHandler 事件数据

x

当前指针（手指或在有多根手指时的主指针）相对于绑定到处理器的视图的X坐标，以点为单位表示。

y

当前指针（手指或在有多根手指时的主指针）相对于绑定到处理器的视图的Y坐标，以点为单位表示。

absoluteX

当前指针（手指或在有多根手指时的主指针）相对于窗口的X坐标，以点为单位表示。在绑定到处理器的视图可能会因手势而发生变换的情况下，建议使用absoluteX而不是x。

absoluteY

当前指针（手指或在有多根手指时的主指针）相对于窗口的Y坐标，以点为单位表示。在绑定到处理器的视图可能会因手势而发生变换的情况下，建议使用absoluteY而不是y。

遗留问题

其他

开源协议

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