react-native-sortable-grid

本项目基于 react-native-sortable-grid开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

@hxa-rn/react-native-sortable-grid 是 React Native 拖拽排序网格组件 react-native-sortable-grid 的鸿蒙适配包，当前版本 2.0.1-beta.1。

本库为 js-only 实现，无 TurboModule / Fabric / C++ Package。核心能力：

• 长按激活拖拽，拖动时其余块平滑交换位置，释放后回调最新顺序
• 删除模式：toggleDeleteMode() 切换后向下拖拽删除子项
• 自定义拖拽起始动画（dragStartAnimation）
• 子项单击 / 双击回调，以及 inactive 非交互标记
• 按 itemsPerRow / itemWidth / itemHeight 自适应网格布局

集成指南

npm install @hxa-rn/react-native-sortable-grid

在鸿蒙工程的 Metro / harmony.alias 配置下，业务代码仍从原包名导入：

import SortableGrid from 'react-native-sortable-grid';

适配包 package.json 已声明 "harmony": { "alias": "react-native-sortable-grid" }，无需改业务 import 路径。运行时依赖 lodash 已随本包安装。

使用说明

import React, { useRef } from 'react';
import { View, Text, Button } from 'react-native';
import SortableGrid from 'react-native-sortable-grid';

export function Demo() {
  const gridRef = useRef<any>(null);

  return (
    <View>
      <Button
        title="切换删除模式"
        onPress={() => {
          const res = gridRef.current?.toggleDeleteMode?.();
          console.log('deleteModeOn', res?.deleteModeOn);
        }}
      />
      <SortableGrid
        ref={gridRef}
        itemsPerRow={4}
        dragActivationTreshold={200}
        onDragStart={(item) => console.log('start', item)}
        onDragRelease={({ itemOrder }) => console.log('order', itemOrder)}
        onDeleteItem={({ item }) => console.log('deleted', item?.key)}
      >
        {['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'].map((letter) => (
          <View key={letter} style={{ flex: 1, margin: 8, backgroundColor: '#E91E63' }}>
            <Text>{letter}</Text>
          </View>
        ))}
      </SortableGrid>
    </View>
  );
}

子项可额外设置 onTap / onDoubleTap / inactive（挂在 children 的 props 上）。

接口文档

SortableGrid Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | blockTransitionDuration | number | 300 | 被动块位置交换过渡时长（毫秒） | | activeBlockCenteringDuration | number | 200 | 拖拽块释放后归位时长（毫秒） | | itemsPerRow | number | 4 | 每行项目数 | | itemWidth | number | — | 设置后按网格宽度自动计算 itemsPerRow | | itemHeight | number | — | 配合 itemsPerRow 设置非正方形块高度 | | dragActivationTreshold | number | 200 | 长按激活拖拽的时长阈值（毫秒） | | doubleTapTreshold | number | 150 | 区分单击 / 双击的等待时长（毫秒） | | onDragStart | (activeItem) => void | — | 拖拽开始回调 | | onDragRelease | ({ itemOrder }) => void | — | 拖拽释放回调，返回最新顺序 | | onDeleteItem | ({ item }) => void | — | 项目删除回调 | | dragStartAnimation | { transform: any[] } | — | 自定义拖拽起始动画，覆盖默认抖动 | | style | object | — | 自定义网格样式 | | children | Node[] | — | 网格子项 |

onDragRelease 回调结构：

{
  itemOrder: [
    { key: "1", order: 0, ref: null },
    { key: "5", order: 1, ref: null }
  ]
}

实例方法

| 方法 | 参数 | 返回 | 说明 | |------|------|------|------| | toggleDeleteMode() | 无 | { deleteModeOn: boolean } | 切换删除模式 |

子项 Props

| 属性 | 类型 | 说明 | |------|------|------| | onTap | function | 单击回调（未设置 onDoubleTap 时立即触发） | | onDoubleTap | function | 双击回调（设置后会延迟 onTap） | | inactive | boolean | 为 true 时不响应单击、双击与拖拽 |

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 12+ |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-sortable-grid.git
cd react-native-sortable-grid
git checkout br_rnoh0.72

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• 鸿蒙 SDK：API 12+（示例工程 compatibleSdkVersion 5.0.1(13)）
• 上游 RN SDK：react-native-sortable-grid 2.0.1
• React Native / RNOH：>= 0.72

权限

• 无额外系统权限。

平台说明：本库为 js-only，无需 Autolink / HAR / C++ Package 注册。拖拽依赖 PanResponder 的 moveX/moveY，真机上需确认长按激活与坐标跟随。源码保留 componentWillMount / componentWillReceiveProps，可能输出 UNSAFE 告警，不影响功能。

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

欢迎在 AtomGit 仓库提交 Issue，或通过 HXA-RN 社区交流。

• 仓库：https://gitcode.com/hxa-rn/react-native-sortable-grid
• Issue：https://gitcode.com/hxa-rn/react-native-sortable-grid/issues