基于 DragListDemo 实战验证，覆盖拖拽排序、手势组合、冲突处理，附带完整可运行代码

---

写在前面

拖拽排序这功能，看着简单——不就是拖一个 item 放到另一个位置嘛。但在 HarmonyOS 上实现，坑比想象的多。数据重排后 UI 不更新、ForEach 缺 key 导致错乱、拖拽和滚动手势冲突……光解决这些问题就花了我两天。

这篇文章把拖拽排序的完整实现过程和踩过的坑全写出来，希望后来的人能一天搞定。

---

一、拖拽排序的核心流程

拖拽排序分三步：

1. 开始拖拽：记录被拖拽项的索引
2. 拖拽经过：高亮目标位置
3. 放下：重排数据数组

开始拖拽

private handleDragStart(index: number): void {
  this.dragIndex = index
  this.addLog('开始拖拽: index=' + index.toString())
}

高亮目标位置

.onDragEnter(() => { this.hoverIndex = index })
.onDragLeave(() => { if (this.hoverIndex === index) { this.hoverIndex = -1 } })

放下重排

这是最关键的一步，也是最容易出 bug 的地方：

private handleDrop(targetIndex: number): void {
  if (this.dragIndex < 0 || this.dragIndex === targetIndex) {
    this.dragIndex = -1
    return
  }
  const item: DragItem = this.items[this.dragIndex]
  const newItems: DragItem[] = this.items.slice()
  newItems.splice(this.dragIndex, 1)
  if (targetIndex > this.dragIndex) {
    targetIndex = targetIndex - 1
  }
  newItems.splice(targetIndex, 0, item)
  this.items = newItems  // 必须重新赋值！
  this.dragIndex = -1
  this.hoverIndex = -1
}

踩坑一：splice 后必须重新赋值

@State 数组的观测机制是基于引用的。如果你直接 this.items.splice(...) 修改原数组，@State 检测不到变化，UI 不会更新。

正确做法：先 slice 复制，splice 修改副本，再整体赋值回 @State。

// 错误：直接修改原数组，UI 不更新
this.items.splice(fromIndex, 1)
this.items.splice(toIndex, 0, item)

// 正确：复制→修改→重新赋值
const newItems: DragItem[] = this.items.slice()
newItems.splice(fromIndex, 1)
newItems.splice(toIndex, 0, item)
this.items = newItems

这个坑不只拖拽排序会遇到，所有 @State 数组的增删改都有这个问题。记住了：@State 数组修改后必须重新赋值。

踩坑二：目标索引偏移

从原位置删除元素后，目标位置之后的索引都会前移一位。如果目标索引大于拖拽起始索引，需要减 1：

if (targetIndex > this.dragIndex) {
  targetIndex = targetIndex - 1
}

不减 1 的话，拖到后面的位置会多偏移一位，体验就是"明明放这了，结果跳到前面去了"。

---

二、方法命名的坑

这坑藏得特别深。我一开始把方法命名为 onDragStart 和 onDrop，编译报错：

Property 'onDragStart' in type 'DragListDemo' is not assignable to the same property in base type 'CustomComponent'.

原因：onDragStart 和 onDrop 是组件的内置事件属性名！你在 struct 里定义同名方法，ArkTS 认为你在覆盖父类型属性，类型不匹配就报错。

解决方法：换个名字。改成 handleDragStart、handleDrop 就好了：

// 错误：与组件内置事件名冲突
private onDragStart(index: number): void { ... }
private onDrop(targetIndex: number): void { ... }

// 正确：避开内置名称
private handleDragStart(index: number): void { ... }
private handleDrop(targetIndex: number): void { ... }

这个坑不只会出现在拖拽场景。ArkTS 组件有很多内置事件（onClick、onTouch、onAppear……），自定义方法名一定要避开这些。

---

三、ForEach 的 key 不能省

拖拽排序后，ForEach 需要通过 key 判断哪些项需要更新。如果省略 key 或者 key 不唯一，UI 会错乱：

// 错误：没有 key
ForEach(this.items, (item: DragItem) => { ... })

// 正确：用唯一 id 作为 key
ForEach(this.items, (item: DragItem) => { ... }, (item: DragItem) => item.id.toString())

踩坑三：用 index 做 key 的后果

有些人图省事用 index 做 key：(item, index) => index.toString()。拖拽排序后，index 变了但 item 的 id 没变，ForEach 会错误地复用旧位置的组件，导致渲染错位。

key 必须是稳定的唯一标识，通常是数据模型的 id 字段。

---

四、长按触发拖拽

直接拖拽容易误触，加一个长按手势作为触发条件更合理：

.gesture(
  LongPressGesture({ repeat: false, duration: 300 })
    .onAction(() => { this.handleDragStart(index) })
)

300ms 的长按延迟是个经验值。太短（100ms）容易误触，太长（500ms）用户等得不耐烦。300ms 是移动端比较公认的"短长按"阈值。

---

五、拖拽与滚动的冲突

拖拽排序最常见的场景是在列表里。但列表本身有滚动手势，两者会冲突：

• 用户想拖拽 item → 结果触发了滚动
• 用户想滚动列表 → 结果触发了拖拽

解决方案一：长按区分

用 LongPressGesture 触发拖拽，普通的滑动就是滚动。手势系统会自动区分长按和滑动，这是最推荐的方案。

解决方案二：priorityGesture

如果拖拽手势必须优先于滚动，可以用 priorityGesture：

.priorityGesture(
  PanGesture()
    .onActionStart(() => { ... })
)

但这会导致列表无法正常滚动，除非拖拽区域很小（比如拖拽手柄图标）。

解决方案三：拖拽手柄

最稳妥的方案：列表项整体响应滚动，只有侧边的拖拽手柄（≡ 图标）响应拖拽。手势天然隔离，不存在冲突。

Row() {
  Text('≡')  // 拖拽手柄，只在这里响应拖拽
    .gesture(PanGesture().onActionStart(() => { ... }))
  Column() {
    Text(item.title)  // 内容区域，正常响应滚动
  }
}

---

六、LazyForEach 拖拽排序

如果列表用 LazyForEach 而不是 ForEach，拖拽排序后需要调用 notifyDataChange 通知数据源更新：

private dataSource: MyIDataSource = new MyIDataSource()

// 拖拽完成后
handleDrop(targetIndex: number): void {
  // ...重排数据...
  this.dataSource.notifyDataChange(targetIndex)
  this.dataSource.notifyDataChange(this.dragIndex)
}

LazyForEach 不会自动检测数组变化，必须手动通知。这是 LazyForEach 性能优势的代价。

---

七、拖拽排序 vs 其他排序方式

方式	交互	反馈	适用场景	实现难度
拖拽排序	长按+拖	实时预览	少量项目/用户自定义	高
上下按钮	点击按钮	离散移动	固定顺序/设置项	低
编辑+保存	表单式	提交生效	批量调整顺序	中

拖拽排序的实现难度最高，但用户体验也最好。如果列表项不超过 20 个，优先用拖拽；超过 20 个，拖拽操作会很累，建议用上下按钮。

---

八、手势优先级体系

HarmonyOS 的手势分三个优先级：

1. gesture：默认优先级，与子组件手势协商
2. priorityGesture：高优先级，父组件先识别
3. parallelGesture：并行，父子同时响应

拖拽排序场景下，如果列表项内部也有手势（比如滑动删除），就需要用 priorityGesture 让拖拽手势优先。否则内部的滑动手势会"吃掉"拖拽事件。

---

写在最后

拖拽排序的实现确实比想象中复杂，但核心就三步：记录起点、高亮目标、重排数据。只要记住 @State 数组修改后必须重新赋值、ForEach 的 key 不能省、方法名避开内置事件名，基本不会踩大坑。

如果列表项很多，建议加上拖拽手柄（≡ 图标）隔离手势冲突，比全局优先级方案更稳定。用户体验也好——用户知道要拖哪里，不会误触。