react-native-sortable-grid

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

项目介绍

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

本库为 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 main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-sortable-grid@2.0.4，不再使用本地 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