@ohmi/react-native-gesture-handler
v2.14.1-2.14.17
Published
> 模板版本：v0.2.2
Keywords
Readme
模板版本：v0.2.2
[!TIp] Git 地址
介绍
该项目基于react-native-gesture-handler开发。
安装与使用
进入到工程目录并输入以下命令：
npm
npm install @ohmi/react-native-gesture-handleryarn
yarn add @ohmi/react-native-gesture-handler下面的代码展示了这个库的基本使用场景：
[!WARNING] 使用时 import 的库名不变。
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 />;
}使用Codegen
本库未带rc.x的版本号是已经适配了 Codegen ，在使用前需要主动执行生成三方库桥接代码，详细请参考 Codegen 使用文档。
Link
目前 HarmonyOS 暂不支持 AutoLink，所以 Link 步骤需要手动配置。
首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony
1.在工程根目录的 oh-package.json5 添加 overrides 字段
{
...
"overrides": {
"@rnoh/react-native-openharmony" : "./react_native_openharmony"
}
}2.引入原生端代码
[!TIP] 引入原生代码之前请确认IDE版本，5.0.3.810及其之后的版本需要在harmony工程中的hvigor-config.json5文件中新增如下配置以解决路径过长导致的编译报错问题 "properties":{ "ohos.nativeResolver":false }
目前有两种方法：
- 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
- 直接链接源码。
方法一：通过 har 包引入（推荐）
[!TIP] har 包位于三方库安装路径的
harmony文件夹下。
打开 entry/oh-package.json5，添加以下依赖
"dependencies": {
"@rnoh/react-native-openharmony": "file:../react_native_openharmony",
"@ohmi/react-native-gesture-handler": "file:../../node_modules/@ohmi/react-native-gesture-handler/harmony/gesture_handler.har"
}点击右上角的 sync 按钮
或者在终端执行：
cd entry
ohpm install方法二：直接链接源码
[!TIP] 如需使用直接链接源码，请参考直接链接源码说明
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}/@ohmi/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 '@ohmi/react-native-gesture-handler/ts';
export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
return [
new SamplePackage(ctx),
+ new GestureHandlerPackage(ctx),
];
}5.运行
点击右上角的 sync 按钮
或者在终端执行：
cd entry
ohpm install在vscode终端运行 npm run codegen
然后编译、运行即可。
约束与限制
4.API reference
4.1 Components
4.1.1 Touchables
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) ，请自由地享受和参与开源。