@react-native-ohos/react-native-drax

v1.0.0

Published

2 months ago

A drag-and-drop system for React Native

文档模板：v0.4.2

本项目基于 react-native-drax 开发。

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

| 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 | | ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | | @react-native-ohos/react-native-drax | ~ 1.0.0 | Gitcode Releases | 0.82.* | 否 | API12+ | 1.1.0 | br_rnoh0.82 | | @react-native-ohos/react-native-drax | ~ 0.12.0 | Gitcode Releases | 0.77.* | 否 | API12+ | 0.12.0 | br_rnoh0.77 | | @react-native-ohos/react-native-drax | ~ 0.10.4 | Gitcode Releases | 0.72.* | 否 | API12+ | 0.10.4 | br_rnoh0.72 | | @react-native-oh-tpl/react-native-drax | <= 0.10.3-0.0.1@deprecated | Github Releases(deprecated) | 0.72.* | 否 | API12+ | 0.10.3 | sig |

简介

react-native-drax 是一个 React Native 的拖拽库，提供跨平台的拖拽功能支持。它提供了 DraxProvider、DraxView、DraxList、DraxScrollView 等组件，支持拖拽检测、拖拽样式、拖拽传递数据、列表项重新排序等功能。

下载安装

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

npm

npm install @react-native-ohos/react-native-drax

yarn

yarn add @react-native-ohos/react-native-drax

Link

本库实现依赖 react-native-reanimated、react-native-gesture-handler的原生端代码，如已在鸿蒙工程中引入过该库，则无需再次引入，可跳过本章节步骤，直接使用。

请参照以下文档进行引入：react-native-reanimated 文档、react-native-gesture-handler 文档。

约束与限制

兼容性

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

RNOH: 0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM: 6.0.0.120 SP7;

权限要求

本库为纯 JS 库，无需申请额外权限。

使用示例

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

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

import React, { useState } from 'react';
import { View, StyleSheet } from 'react-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { DraxProvider, DraxView } from 'react-native-drax';


export const GestureHandleExample = () => {
  return (
    <DraxProvider>
      <GestureHandlerRootView>
        <View style={styles.container}>
          <DraxView
            style={styles.draggable}
            onDragStart={() => {
              console.log('start drag');
            }}
            payload="world"
          />
          <DraxView
            style={styles.receiver}
            onReceiveDragEnter={({ dragged: { payload } }) => {
              console.log(`hello ${payload}`);
            }}
            onReceiveDragExit={({ dragged: { payload } }) => {
              console.log(`goodbye ${payload}`);
            }}
            onReceiveDragDrop={({ dragged: { payload } }) => {
              console.log(`received ${payload}`);
            }}
          />
        </View>
      </GestureHandlerRootView>
    </DraxProvider>
  );
};

const styles = StyleSheet.create({
  box: {
    width: 100,
    height: 100,
    backgroundColor: 'blue',
    marginTop: 100,
    marginLeft: 100
  },
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    width: '100%',
    height: 800,
    paddingTop: 500
  },
  draggable: {
    width: 100,
    height: 100,
    backgroundColor: 'blue',
  },
  receiver: {
    width: 100,
    height: 100,
    backgroundColor: 'green',
  },
});

使用说明

DraxView 拖拽基础

<DraxView
  style={styles.draggable}
  payload="hello"
  onDragStart={() => console.log('drag start')}
  onDragEnd={() => console.log('drag end')}
/>

DraxList 列表排序

const [data, setData] = useState([
  { id: '1', text: 'Task 1' },
  { id: '2', text: 'Task 2' },
]);

<DraxList
  data={data}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <Text>{item.text}</Text>}
  onReorder={({ data: newData }) => setData(newData)}
/>

DraxScrollView 滚动拖拽

<DraxScrollView style={{ height: 400 }}>
  <DraxView style={styles.item} payload="item1" />
  <DraxView style={styles.item} payload="item2" />
</DraxScrollView>

接口说明

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "OpenHarmony Support"列为 yes 表示 OpenHarmony平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

组件

| 名称 | 参数类型 | 必填 | 平台 | OpenHarmony平台支持| 描述 | |------------|------------|----------------------|------|-----|----------------| | DraxProvider | DraxProviderProps | yes | all | yes | 拖拽上下文提供者组件，必须包裹所有 Drax 组件 | | DraxView | DraxViewProps | no | all | yes | 可拖拽视图组件 | | DraxHandle | DraxHandleProps | no | all | yes | 拖拽手柄组件，配合 DraxView 的 dragHandle 属性使用 | | DraxList | DraxListProps | no | all | yes | 支持拖拽排序的列表组件，可适配 FlatList、FlashList 等任意列表组件 | | DraxScrollView | DraxScrollViewProps | no | all | yes | 支持拖拽和自动滚动的滚动视图组件 |

属性

DraxProvider

DraxView

DraxHandle

DraxScrollView

DraxList

遗留问题

[ ] DraxList和DraxScrollView组件存在拖拽不流畅的情况，issue#1
[ ] DraxView的otherDraggingWithReceiverStyle属性不生效，issue#13
[ ] DraxView的otherDraggingWithoutReceiverStyle属性不生效，issue#14
[ ] DraxList的itemExiting属性不生效，issue#15

其他

无

目录结构

/rntpc_react-native-drax  # 项目根目录
├── src                      # RN源码
│    ├── compat              # 兼容层（react-native-gesture-handler 版本差异适配）
│    │    ├── index.ts
│    │    ├── detectVersion.ts
│    │    ├── types.ts
│    │    └── useDraxPanGesture.ts
│    ├── hooks               # 自定义 Hooks
│    │    ├── index.ts
│    │    ├── useCallbackDispatch.tsx
│    │    ├── useDragGesture.ts
│    │    ├── useDraxContext.ts
│    │    ├── useDraxId.ts
│    │    ├── useDraxMethods.ts
│    │    ├── useDraxScrollHandler.ts
│    │    ├── useSortableBoard.ts
│    │    ├── useSortableList.ts
│    │    ├── useSpatialIndex.ts
│    │    ├── useViewStyles.ts
│    │    └── useWebScrollFreeze.ts
│    ├── index.ts            # 入口文件（对外导出）
│    ├── Drax.ts             # Drax 命名空间对象
│    ├── DraxContext.ts      # Drax 上下文
│    ├── DraxHandle.tsx      # DraxHandle 组件
│    ├── DraxHandleContext.ts
│    ├── DraxList.tsx        # DraxList 组件
│    ├── DraxProvider.tsx    # DraxProvider 组件
│    ├── DraxScrollView.tsx  # DraxScrollView 组件
│    ├── DraxSubprovider.tsx
│    ├── DraxView.tsx        # DraxView 组件
│    ├── HoverLayer.tsx      # 拖拽悬停层
│    ├── DebugOverlay.tsx    # 调试浮层
│    ├── SortableBoardContainer.tsx  # SortableBoardContainer 组件
│    ├── SortableBoardContext.ts
│    ├── SortableContainer.tsx       # SortableContainer 组件
│    ├── SortableItem.tsx            # SortableItem 组件
│    ├── SortableItemContext.ts      # SortableItem 上下文
│    ├── math.ts             # 数学工具（snapToAlignment、packGrid 等）
│    ├── params.ts           # 默认参数配置
│    └── types.ts            # 类型定义
├── lib                       # 构建产物
├── example                   # 示例项目
├── docs                      # 文档
├── README.md                 # 中文安装使用方法
├── README_en.md              # 英文安装使用方法

贡献代码

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

开源协议

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