一、引言

拖拽排序（Drag-to-Sort）是移动端应用中最常见的交互模式之一——待办事项列表调整优先级、播放列表重新排列、相册照片排序等场景都依赖于这一交互。用户通过长按并拖拽列表项将其移动到新的位置，其他项自动让位，形成流畅的重排体验。

在 HarmonyOS NEXT 中，拖拽排序的核心依赖 PanGesture 手势识别和数组操作逻辑。与传统的拖拽事件（DragEvent）不同，PanGesture 提供了更精细的触摸跟踪能力，允许开发者实时获取手指偏移量并动态更新 UI。

本文将通过一个完整的实战项目，系统讲解如何使用 PanGesture 实现列表拖拽排序，涵盖手势绑定、排序算法、视觉反馈和状态管理。

---

二、核心原理

2.1 拖拽排序的架构

一个完整的拖拽排序功能由三个角色协作完成：

父组件（DragToSortDemo）
  ├── 管理列表数据（@State items）
  ├── 执行排序算法（moveItem）
  └── 管理拖拽状态（dragIndex, dragOffsetY）

子组件（SortableItem）
  ├── 绑定 PanGesture
  ├── 上报手指偏移量
  └── 根据拖拽状态切换视觉样式

2.2 排序算法

拖拽排序的核心算法可以概括为三步：

1. 累加偏移：dragOffsetY += event.offsetY
2. 计算步数：moveStep = Math.round(dragOffsetY / itemHeight)
3. 计算目标：newTarget = dragIndex + moveStep
4. 边界限制：clamp(0, len-1, newTarget)
5. 如果目标变化 → 执行数组移动 → 更新 dragIndex

2.3 视觉反馈三要素

拖拽排序需要三种视觉反馈来引导用户：

反馈	实现方式	效果
被拖拽项跟随手指	.translate({ y: offsetY })	手指移动时项目实时跟随
被拖拽项视觉提升	.zIndex(100) + .shadow() + 边框高亮	脱离列表层级，显示在顶层
交叉项高亮	根据 dragIndex 改变其他项背景色	指示当前经过的位置

---

三、环境

MyApplication/
└── entry/src/main/
    ├── ets/pages/DragToSortDemo.ets
    └── resources/base/profile/main_pages.json

---

四、完整代码实现

4.1 可拖拽列表项组件（SortableItem）

@Component
struct SortableItem {
  index: number = 0;
  item: string = '';
  dragIndex: number = -1;
  itemOffsetY: number = 0;
  onDragStartCb?: (index: number) => void;
  onDragUpdateCb?: (index: number, offsetY: number) => void;
  onDragEndCb?: (index: number) => void;

  /** 当前是否为被拖拽项 */
  private get isDragging(): boolean {
    return this.dragIndex === this.index;
  }
  /** 当前是否处于交叉位置（其他项拖拽经过） */
  private get isCrossing(): boolean {
    return this.dragIndex >= 0 && this.dragIndex !== this.index;
  }

  build() {
    Column() {
      Row() {
        Text('⠿').fontSize(20).fontColor('rgba(255,255,255,0.3)')
        Text(String(this.index + 1) + '.')
          .fontSize(15).fontColor('rgba(255,255,255,0.5)').width(28)
        Text(this.item).fontSize(15).fontColor(Color.White).layoutWeight(1)
        Text('↕').fontSize(16).fontColor('rgba(255,255,255,0.25)')
      }
      .width('100%').padding(16).alignItems(VerticalAlign.Center)
    }
    .width('100%').borderRadius(12)
    // 背景色：拖拽中金色 / 经过高亮 / 默认半透明
    .backgroundColor(this.isDragging
      ? 'rgba(255,215,0,0.2)'
      : this.isCrossing ? 'rgba(255,255,255,0.12)' : 'rgba(255,255,255,0.06)')
    // 拖拽中金色边框
    .border({
      width: this.isDragging ? 1 : 0,
      color: this.isDragging ? 'rgba(255,215,0,0.5)' : 'rgba(255,255,255,0)'
    })
    // 拖拽中阴影提升
    .shadow({
      radius: this.isDragging ? 16 : 0,
      color: 'rgba(0,0,0,0.4)', offsetY: this.isDragging ? 8 : 0
    })
    .zIndex(this.isDragging ? 100 : 1)
    .translate({ y: this.isDragging ? this.itemOffsetY : 0 })
    // ========== 核心：PanGesture ==========
    .gesture(
      PanGesture({ fingers: 1, direction: PanDirection.Vertical, distance: 10 })
        .onActionStart(() => {
          if (this.onDragStartCb) { this.onDragStartCb(this.index); }
        })
        .onActionUpdate((event: GestureEvent) => {
          if (this.onDragUpdateCb) { this.onDragUpdateCb(this.index, event.offsetY); }
        })
        .onActionEnd(() => {
          if (this.onDragEndCb) { this.onDragEndCb(this.index); }
        })
    )
  }
}

设计要点：

1. 属性命名注意：使用 onDragStartCb / onDragUpdateCb / onDragEndCb 而非 onDragStart / onDragEnd。这是因为 onDragStart 和 onDragEnd 是 ArkUI 内置的拖放事件（DragEvent）属性名，如果使用会导致类型冲突。

2. 三态背景色：

   • isDragging（被拖拽项）：金色半透明背景 + 金色边框 + 阴影，视觉上从列表中"浮起"
   • isCrossing（其他项，但拖拽经过）：浅色高亮，指示当前经过的位置
   • 默认：半透明灰色背景，融入列表

3. PanGesture 参数：

   • direction: PanDirection.Vertical：仅识别垂直方向拖拽，避免水平误触
   • distance: 10：最小触发距离 10vp，防止轻微手指抖动触发拖拽

4.2 主页面组件（DragToSortDemo）

@Entry
@Component
struct DragToSortDemo {
  @State items: string[] = [
    '了解项目需求',
    '设计 UI 原型',
    '搭建开发环境',
    '编写核心功能',
    '编写单元测试',
    '界面联调与优化',
    '提交代码评审',
    '部署到测试环境',
  ];

  @State dragIndex: number = -1;
  @State dragOffsetY: number = 0;
  @State targetIndex: number = -1;
  private readonly itemHeight: number = 56;

  build() {
    Column() {
      // 顶部标题栏
      Row() {
        Text('↕ 拖拽排序 DragToSort').fontSize(20).fontColor('#FFFFFF')
        Blank()
        Button('重置').onClick(() => { this.resetItems(); })
      }.height(56).backgroundColor('rgba(0,0,0,0.3)')

      Text('💡 拖拽手柄 ↕ 上下拖动以重新排序')
        .fontSize(12).fontColor('rgba(255,255,255,0.5)').padding(8)

      // 列表
      Scroll() {
        Column() {
          ForEach(this.items, (item: string, index: number) => {
            SortableItem({
              index: index,
              item: item,
              dragIndex: this.dragIndex,
              itemOffsetY: index === this.dragIndex ? this.dragOffsetY : 0,
              onDragStartCb: (idx) => this.handleDragStart(idx),
              onDragUpdateCb: (idx, offsetY) => this.handleDragUpdate(idx, offsetY),
              onDragEndCb: (idx) => this.handleDragEnd(idx),
            })
          })
          Blank().height(30)
        }.padding({ left: 16, right: 16, top: 8 })
      }.layoutWeight(1)

      // 底部状态栏
      Row() {
        Text('共 ' + this.items.length + ' 项')
        if (this.dragIndex >= 0) {
          Text('拖拽中: 第 ' + (this.dragIndex + 1) + ' 项')
        }
      }.padding({ left: 16, right: 16, top: 8, bottom: 12 })
      .backgroundColor('rgba(0,0,0,0.15)')
    }
    .width('100%').height('100%')
    .linearGradient({
      direction: GradientDirection.Bottom,
      colors: [['#1a1a2e', 0], ['#16213e', 0.5], ['#0f3460', 1]]
    })
  }

  /** 拖拽开始 */
  handleDragStart(index: number): void {
    this.dragIndex = index;
    this.dragOffsetY = 0;
    this.targetIndex = index;
  }

  /** 拖拽更新 —— 核心排序逻辑 */
  handleDragUpdate(index: number, offsetY: number): void {
    if (this.dragIndex < 0) return;

    this.dragOffsetY += offsetY;

    // 计算目标位置
    const moveStep = Math.round(this.dragOffsetY / this.itemHeight);
    const newTarget = this.dragIndex + moveStep;
    const clampedTarget = Math.max(0, Math.min(this.items.length - 1, newTarget));

    // 目标变化时执行移动
    if (clampedTarget !== this.targetIndex) {
      this.targetIndex = clampedTarget;
      const oldDragIndex = this.dragIndex;
      this.dragIndex = this.targetIndex;
      this.dragOffsetY = 0;
      this.moveItem(oldDragIndex, this.dragIndex);
    }
  }

  /** 拖拽结束 */
  handleDragEnd(index: number): void {
    this.dragIndex = -1;
    this.dragOffsetY = 0;
    this.targetIndex = -1;
  }

  /** 移动数组元素（从 from 移到 to） */
  moveItem(from: number, to: number): void {
    if (from === to) return;

    const newItems: string[] = [];
    for (let i = 0; i < this.items.length; i++) {
      newItems.push(this.items[i]);
    }
    const moved: string = newItems[from];
    // 删除原位置
    for (let i = from; i < newItems.length - 1; i++) {
      newItems[i] = newItems[i + 1];
    }
    // 插入到目标位置
    for (let i = newItems.length - 1; i > to; i--) {
      newItems[i] = newItems[i - 1];
    }
    newItems[to] = moved;
    this.items = newItems;
  }

  resetItems(): void {
    this.items = [
      '了解项目需求', '设计 UI 原型', '搭建开发环境',
      '编写核心功能', '编写单元测试', '界面联调与优化',
      '提交代码评审', '部署到测试环境',
    ];
    this.dragIndex = -1;
    this.dragOffsetY = 0;
    this.targetIndex = -1;
  }
}

4.3 核心排序算法详解

拖拽更新流程（handleDragUpdate）：

用户手指上滑 20vp
  → event.offsetY = -20
  → dragOffsetY 累加 = -20
  → moveStep = round(-20 / 56) = 0   // 尚未超过半项，不交换
  → 继续上滑到 35vp
  → dragOffsetY 累加 = -35
  → moveStep = round(-35 / 56) = -1   // 超过半项，向上移1位
  → newTarget = dragIndex + (-1)       // 目标索引减1
  → 执行 moveItem(from, to)
  → dragOffsetY 重置为 0
  → dragIndex 更新为新位置

为何重置 dragOffsetY：每次执行数组移动后，dragIndex 已经更新为新的位置。重置 dragOffsetY 可以让下一次累积从零开始，避免偏移量持续累积导致"穿越"多个项目。

moveItem 函数的算法：

由于 ArkTS 不支持 Array.splice()（API 12+ 限制）或解构赋值语法，这里使用纯循环实现：

// 1. 复制数组
// 2. 取出 from 位置的元素
// 3. 从 from 到 len-1，逐个前移覆盖
// 4. 从 len-1 到 to，逐个后移腾出空间
// 5. 在 to 位置放入取出的元素

---

五、进阶技巧

5.1 视觉反馈强度控制

拖拽排序的良好体验很大程度上依赖视觉反馈。以下是推荐的反馈参数：

反馈项	参数	效果
阴影	radius: 16, offsetY: 8	适度的浮起感
边框	width: 1, color: 金色半透明	清晰的选中标识
背景色	rgba(255,215,0,0.2)	金色背景，不遮盖文字
层级	zIndex: 100	确保在列表顶层
经过高亮	rgba(255,255,255,0.12)	轻微高亮，指示位置

5.2 手指防误触

PanGesture 的 distance 参数是防止误触的关键：

PanGesture({ distance: 10 })

• 太小（如 3vp）：手指轻微抖动就会触发拖拽，列表频繁跳闪
• 太大（如 30vp）：用户需要大幅度滑动才能触发，体验迟滞
• 推荐 10vp：平衡灵敏度和稳定性

5.3 列表项高度的一致性

排序算法的精度依赖于 itemHeight 的准确性。如果列表项高度不一致，排序计算会产生偏差。解决方案：

1. 统一高度：设计上保证所有列表项高度一致（推荐）
2. 动态获取：通过 .onAreaChange() 在运行时获取每项的实际高度并缓存
3. 平均估算：取前几项高度的平均值作为估算值

5.4 性能优化

当列表项较多时（超过 20 项），频繁的数组重排可能导致性能问题：

1. 使用 LazyForEach：替换 ForEach 为 LazyForEach 实现懒加载
2. 减少状态更新频率：在 onActionUpdate 中限制排序计算的触发频率（例如每 50ms 计算一次）
3. 使用 DataSource：封装数据源类管理列表数据，避免全量复制

---

六、常见问题

Q1：为什么不能用 Array.splice() 实现数组移动？

A：ArkTS 是 TypeScript 的子集，对 JavaScript 的某些动态特性有限制。在 API 12+ 中，Array.splice() 等变异方法可能不被支持（具体取决于 SDK 版本）。使用纯循环实现可以保证兼容性。

Q2：拖拽时列表项为什么闪烁？

A：可能原因：dragOffsetY 没有在数组移动后重置为 0；或者 itemHeight 与实际高度不一致导致计算偏差。检查 handleDragUpdate 中是否在 dragIndex 更新后重置了偏移量。

Q3：为什么 onDragStart 和 onDragEnd 不能用？

A：onDragStart 和 onDragEnd 是 ArkUI 的 DragEvent（拖放事件）的属性名，用于系统级拖放操作。自定义回调需使用其他名称如 onDragStartCb。

Q4：如何让列表同时支持垂直滚动和拖拽排序？

A：这是最常见的冲突场景。解决方案：

• 拖拽触发条件设为较长的 distance（如 15vp），让 Scroll 先响应滚动
• 在 onActionStart 中禁用 Scroll（通过状态变量控制）
• 拖拽结束时恢复 Scroll

Q5：拖拽排序可以和动画结合吗？

A：可以。在 handleDragEnd 中使用 animateTo 实现松手回弹效果。但需要注意 animateTo 在 ArkTS API 24 中已被标记为废弃，建议使用 animation 属性替代。

---

七、总结

本文通过一个完整的拖拽排序实战项目，系统讲解了以下关键技术：

技术	实现	作用
PanGesture	PanGesture(Vertical, distance:10)	识别垂直拖拽手势
位置跟随	.translate({ y: offsetY })	被拖拽项跟随手指
视觉提升	.zIndex(100) + .shadow() + 边框	拖拽项"浮起"效果
排序算法	offset / itemHeight + 边界限制	计算目标位置
数组移动	纯循环实现 moveItem	重排列表数据
三态样式	isDragging / isCrossing / 默认	视觉反馈

核心公式：

dragOffsetY += event.offsetY
moveStep = round(dragOffsetY / itemHeight)
newIndex = clamp(0, len-1, dragIndex + moveStep)
→ 目标变化 → moveItem(from, to) → 界面重排

拖拽排序是一个将手势识别、数据操作和视觉反馈紧密结合的经典交互模式。掌握这套实现方案，可以为鸿蒙应用中的列表、网格、卡片等场景轻松添加拖拽重排能力。