# ty-react-native-gesture-handler

**Repository Path**: kunyuan-hongke/ty-react-native-gesture-handler

## Basic Information

- **Project Name**: ty-react-native-gesture-handler
- **Description**: ty-react-native-gesture-handler库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-04-28
- **Last Updated**: 2025-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

> 模板版本：v0.2.2

<p align="center">
  <h1 align="center"> <code>react-native-gesture-handler</code> </h1>
</p>
<p align="center">
        <a href="https://gitee.com/link?target=https%3A%2F%2Fgithub.com%2Fsoftware-mansion%2Freact-native-gesture-handler">
        <img src="https://img.shields.io/badge/platforms-android%20%7C%20ios%20%7C%20harmony%20-lightgrey.svg" alt="Supported platforms" />
    </a>
    <a href="https://gitee.com/link?target=https%3A%2F%2Fgithub.com%2Fsoftware-mansion%2Freact-native-gesture-handler%2Fblob%2Fmain%2FLICENSE">
        <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" />
    </a>
</p>



> [!TIP] [Github 地址](https://gitee.com/link?target=https%3A%2F%2Fgithub.com%2Freact-native-oh-library%2Freact-native-harmony-gesture-handler)

## 安装与使用

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

<!-- tabs:start -->

#### **npm**

```bash
npm install @tuya-oh/react-native-gesture-handler
```

#### **yarn**

```bash
yarn add @tuya-oh/react-native-gesture-handler
```

<!-- tabs:end -->

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

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

```tsx
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 使用文档](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/codegen.md)。

## Link

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

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

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

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

### 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`，添加以下依赖

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

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

点击右上角的 `sync` 按钮

或者在终端执行：

```bash
cd entry
ohpm install
```

方法二：直接链接源码

> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/link-source-code.md)

### 3.配置 CMakeLists 和引入 GestureHandlerPackage

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

```diff
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}/@tuya-oh/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`，添加：

```diff
#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`，添加：

```diff
+ import { GestureHandlerPackage } from '@tuya-oh/react-native-gesture-handler/ts';

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

### 5.运行

点击右上角的 `sync` 按钮

或者在终端执行：

```bash
cd entry
ohpm install
```

**在vscode终端运行 `npm run codegen`**

然后编译、运行即可。

## 约束与限制

## 4.API reference

### 4.1 Components

#### 4.1.1 Touchables

- [Touchable Opacity](https://gitee.com/link?target=https%3A%2F%2Freactnative.dev%2Fdocs%2Ftouchableopacity)
- [Touchable Without Feedback](https://gitee.com/link?target=https%3A%2F%2Freactnative.dev%2Fdocs%2Ftouchablewithoutfeedback)
- [Touchable Highlight](https://gitee.com/link?target=https%3A%2F%2Freactnative.dev%2Fdocs%2Ftouchablehighlight)

#### 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)](https://gitee.com/link?target=https%3A%2F%2Fgithub.com%2Freact-native-oh-library%2Freact-native-linear-gradient%2Fblob%2Fharmony%2FLICENSE) ，请自由地享受和参与开源。