简介：这份资源面向具备一定 Android 基础的开发者，聚焦 RecyclerView 中侧滑拖拽这一常见交互的实现，帮助读者掌握 ItemTouchHelper 的用法与事件处理思路。压缩包共 44 个文件，以 13 个 xml 布局与配置、11 个 java 源码为主，另含 10 张 png 效果图、3 个 properties 与 3 个 gradle 构建脚本，以及 bat、gradlew、jar 等工程辅助文件，整体约 763KB，可直接导入 Android Studio 运行调试。内容围绕自定义 Adapter 与 ViewHolder、重写 ItemTouchHelper.Callback 的 onMove 与 onSwiped、关联 RecyclerView、数据更新通知及 onChildDraw 自定义绘制等环节展开，并附带源码解析压缩包，便于对照理解拖动与滑动的完整链路。已有 371 人学习，适合想补齐列表交互能力、需要可运行示例参考的开发者。

1. 侧滑删除和长按拖拽，为什么我劝你先别急着上 ItemTouchHelper

列表页里加一个「左滑删除、长按拖动排序」的需求，几乎是每个安卓项目都会撞上的场景。很多人的第一反应是去网上抄一段ItemTouchHelper.SimpleCallback，跑起来看着挺顺，一上真机就翻车：滑到一半卡片卡住不动、拖拽后数据错位、删除后位置全乱、和下拉刷新抢手势。我见过不止一个项目在这块反复返工，最后把整个列表交互推倒重写。

这份资源围绕的就是这个高频痛点：用RecyclerView配合ItemTouchHelper，把侧滑删除和长按拖拽排序两件事一次做对。它适合已经能写基础列表、但对触摸事件分发和 Adapter 数据同步心里没底的安卓开发者，也适合想把现有列表交互做扎实的熟手。下面按「原理立住 → 动手复现 → 坑在哪 → 怎么验证」的顺序拆开讲，代码可以直接抄，参数我会标清楚为什么这么设。

2. 先把 ItemTouchHelper 的手势模型讲透：它到底替你做了什么

2.1 回调里的两个方向参数，决定了你能不能滑

ItemTouchHelper本质是一个挂在RecyclerView上的ItemDecoration加触摸监听器，它把「用户手指在某个 item 上的横向/纵向位移」翻译成回调事件。核心是SimpleCallback的两个方法：getMovementFlags和onMove/onSwiped。前者告诉系统这个 item 允许往哪些方向动，后者接收动作结果。

// 侧滑只允许从右往左，拖拽允许上下 int swipeFlags = ItemTouchHelper.LEFT; int dragFlags = ItemTouchHelper.UP | ItemTouchHelper.DOWN; return makeMovementFlags(dragFlags, swipeFlags);

makeMovementFlags(dragFlags, swipeFlags)的第一个参数是拖拽方向，第二个是侧滑方向。这里有个容易忽略的点：swipeFlags写LEFT表示只响应从右向左滑，如果你写LEFT | RIGHT，用户左右都能滑走，但大多数删除交互只想要单向，避免误触。拖拽方向写UP | DOWN是列表纵向排序的标准配置，横向列表才用LEFT | RIGHT。参数不是随便填的，填错方向的表现是「怎么滑都没反应」，而不是报错，这也是新手最容易卡住的地方。

2.2 为什么数据同步必须放在回调里做，而不是动画结束后

onMove和onSwiped触发时，ItemTouchHelper只负责把 item 的视觉位置挪过去，它不碰你的数据源。也就是说，如果你不在回调里同步List的顺序或删除元素，下一次notifyDataSetChanged或列表滚动复用时会立刻「弹回原位」或者「删错行」。这是血泪经验：动画是视觉层，数据是逻辑层，两层必须手动对齐。

@Override public boolean onMove(RecyclerView rv, RecyclerView.ViewHolder src, RecyclerView.ViewHolder dst) { int from = src.getAdapterPosition(); int to = dst.getAdapterPosition(); if (from == RecyclerView.NO_POSITION || to == RecyclerView.NO_POSITION) return false; Collections.swap(dataList, from, to); // 先换数据 adapter.notifyItemMoved(from, to); // 再通知局部刷新 return true; }

这里用notifyItemMoved而不是notifyDataSetChanged，是因为前者只重绘受影响的两行，动画连贯；后者会让整个列表闪一下，拖拽体验直接崩。getAdapterPosition()返回NO_POSITION的情况在快速滑动时会出现，必须判空，否则Collections.swap直接抛IndexOutOfBoundsException。

2.3 侧滑删除的「后悔药」：先移除视图，再决定数据

onSwiped里最稳的写法是：先从数据源移除，再notifyItemRemoved，最后给一个撤销入口。很多人把顺序写反，先notifyItemRemoved再删数据，结果列表短暂显示错位。正确姿势如下：

@Override public void onSwiped(RecyclerView.ViewHolder vh, int direction) { int pos = vh.getAdapterPosition(); if (pos == RecyclerView.NO_POSITION) return; Item removed = dataList.remove(pos); adapter.notifyItemRemoved(pos); // 这里挂 Snackbar 做撤销，把 removed 和 pos 存起来 }

notifyItemRemoved(pos)会触发该位置的移除动画，后面的 item 自动上移。注意不要在这之后又调一次notifyDataSetChanged，那会把动画打断。撤销逻辑就是把removed重新add(pos, removed)再notifyItemInserted(pos)，位置要还原到原索引，不能简单追加到末尾。

3. 从零复现：一个能跑起来的侧滑拖拽列表

3.1 依赖与布局：RecyclerView 的版本别踩老坑

先确认build.gradle里RecyclerView的依赖是较新的稳定版，老版本在嵌套滚动和 item 动画上有已知问题。布局就是一个标准的RecyclerView，item 布局用CardView包一层，保证侧滑时有圆角和阴影，视觉上更像「卡片被推走」。

implementation 'androidx.recyclerview:recyclerview:1.3.2'

item 布局里根节点建议用MaterialCardView或普通LinearLayout，宽度match_parent，高度固定或wrap_content。不要在 item 根布局上加clickable=true之外的复杂触摸监听，否则会和ItemTouchHelper抢事件。

3.2 写 Callback：把方向、阈值、动画一次配好

完整的ItemTouchHelper.Callback需要覆写四个方法：getMovementFlags、onMove、onSwiped、isLongPressDragEnabled。最后一个返回true表示长按即可拖拽，返回false则需要你自己在onBindViewHolder里给拖拽手柄设置OnTouchListener手动startDrag。

public class SwipeDragCallback extends ItemTouchHelper.SimpleCallback { private final List<String> data; private final Adapter adapter; public SwipeDragCallback(List<String> data, Adapter adapter) { super(ItemTouchHelper.UP | ItemTouchHelper.DOWN, ItemTouchHelper.LEFT); this.data = data; this.adapter = adapter; } @Override public boolean onMove(RecyclerView rv, RecyclerView.ViewHolder src, RecyclerView.ViewHolder dst) { int from = src.getAdapterPosition(); int to = dst.getAdapterPosition(); if (from == RecyclerView.NO_POSITION || to == RecyclerView.NO_POSITION) return false; Collections.swap(data, from, to); adapter.notifyItemMoved(from, to); return true; } @Override public void onSwiped(RecyclerView.ViewHolder vh, int direction) { int pos = vh.getAdapterPosition(); if (pos == RecyclerView.NO_POSITION) return; data.remove(pos); adapter.notifyItemRemoved(pos); } @Override public boolean isLongPressDragEnabled() { return true; } }

构造里super(dragFlags, swipeFlags)直接传方向，省去覆写getMovementFlags。isLongPressDragEnabled返回true是最省事的做法，但要注意：如果 item 内部有EditText或横向滚动的子控件，长按会被子控件吃掉，这时就得改成手柄拖拽。

3.3 挂到 RecyclerView 上：一行 attach 背后的顺序问题

ItemTouchHelper helper = new ItemTouchHelper(new SwipeDragCallback(dataList, adapter)); helper.attachToRecyclerView(recyclerView);

attachToRecyclerView必须在setAdapter之后调用，否则ItemTouchHelper拿不到 adapter 的 item 数量，拖拽边界会算错。另外，如果列表用了LinearLayoutManager，拖拽跨屏时ItemTouchHelper会自动滚动，但前提是RecyclerView的clipToPadding和padding设置合理，否则滚到边缘会卡住。

3.4 侧滑背景：让「删除」看得见

默认侧滑只是把 item 移走，底下是空白。要做出「红色删除背景」，需要在 item 布局里放一个底层View，或者在onChildDraw里自己画。常见做法是 item 根布局用FrameLayout，底层放红色背景加删除图标，上层放内容卡片，侧滑时上层被推走，底层露出来。

@Override public void onChildDraw(Canvas c, RecyclerView rv, RecyclerView.ViewHolder vh, float dX, float dY, int actionState, boolean isCurrentlyActive) { if (actionState == ItemTouchHelper.ACTION_STATE_SWIPE) { View itemView = vh.itemView; // 限制最大位移，避免滑出屏幕 float max = itemView.getWidth() * 0.5f; float clamped = Math.max(dX, -max); itemView.setTranslationX(clamped); } else { super.onChildDraw(c, rv, vh, dX, dY, actionState, isCurrentlyActive); } }

dX是横向位移，负值表示向左。clamped把最大位移限制在 item 宽度的一半，防止用户一滑到底直接飞出屏幕。这个阈值可以按产品要求调，0.3 到 0.5 之间比较常见。注意这里没有调super.onChildDraw，因为我们要自己控制位移；如果调了父类，位移会被重复计算。

4. 避坑排查：这五个问题我几乎每次都能遇到

4.1 滑到一半卡住，松手后弹回

现象：手指滑到一半松开，item 没有继续滑走，而是弹回原位。原因通常是getSwipeThreshold默认值 0.5，位移没超过 item 宽度一半就不触发onSwiped。解决：覆写getSwipeThreshold调低到 0.3 左右，或者覆写getSwipeEscapeVelocity让快速轻扫也能触发。

@Override public float getSwipeThreshold(RecyclerView.ViewHolder vh) { return 0.3f; // 滑过 30% 就判定为删除 }

4.2 拖拽后数据错位，删错行

现象：拖动排序后，点删除删掉的是另一行。原因：onMove里只调了notifyItemMoved没换数据，或者换了数据但用了notifyDataSetChanged导致 position 错乱。解决：严格按「先Collections.swap数据，再notifyItemMoved」的顺序，且全程用getAdapterPosition()而不是getLayoutPosition()。

4.3 和下拉刷新抢手势

现象：列表顶部下拉时，偶尔触发 item 侧滑。原因：SwipeRefreshLayout和ItemTouchHelper都在监听触摸事件，纵向拖拽和下拉刷新冲突。解决：在onMove里判断如果当前是拖拽状态，临时禁用SwipeRefreshLayout的setEnabled(false)，拖拽结束后再恢复。

4.4 长按拖拽和 item 点击冲突

现象：想点开 item，结果长按稍微久一点就进入拖拽。原因：isLongPressDragEnabled返回true时长按阈值和点击手势重叠。解决：要么改成手柄拖拽（返回false，在特定子 View 上startDrag），要么在onItemClick里判断actionState，拖拽中不响应点击。

4.5 删除动画结束后列表闪一下

现象：侧滑删除后，剩余 item 上移动画正常，但动画结束瞬间整个列表闪白。原因：在onSwiped之后又调了notifyDataSetChanged，或者 Adapter 的getItemCount返回了旧数据。解决：只调notifyItemRemoved，确保data.remove在通知之前完成，且 Adapter 内部持有的就是同一个List引用。

5. 进阶验证：用状态机和日志把交互钉死

做到能跑只是及格线，真正上线前我会做两件事：一是给拖拽和侧滑加状态标记，二是用日志验证每个回调的触发顺序。下面这个状态机思路很土但很管用：在 Callback 里维护一个currentAction字段，onMove开始时置为DRAG，onSwiped时置为SWIPE，clearView时复位为NONE。然后在 Adapter 的点击监听里判断currentAction == NONE才响应点击，从根上杜绝手势串扰。

private int currentAction = ItemTouchHelper.ACTION_STATE_IDLE; @Override public void onSelectedChanged(RecyclerView.ViewHolder vh, int actionState) { super.onSelectedChanged(vh, actionState); currentAction = actionState; Log.d("TouchHelper", "state -> " + actionState); } @Override public void clearView(RecyclerView rv, RecyclerView.ViewHolder vh) { super.clearView(rv, vh); currentAction = ItemTouchHelper.ACTION_STATE_IDLE; vh.itemView.setTranslationX(0f); // 复位位移，防止复用错位 }

onSelectedChanged会在拖拽或侧滑开始时回调，actionState取值是ACTION_STATE_DRAG、ACTION_STATE_SWIPE、ACTION_STATE_IDLE。clearView里必须把translationX归零，否则被滑过的 item 复用到别的行时会带着偏移，表现为「莫名其妙有一行是歪的」。这个坑我在三个项目里都见过，属于复用机制下的经典翻车点。

验证方法上，我一般会开一个Debug开关，把onMove的from/to、onSwiped的pos、clearView的复位全部打到 Logcat，然后手动做这几组操作：快速连续拖拽、拖到列表边缘触发自动滚动、侧滑到一半松手、侧滑删除后立刻撤销。每组操作看日志顺序是否和预期一致，尤其是notifyItemMoved和notifyItemRemoved之间有没有夹杂意外的notifyDataSetChanged。这套流程走一遍，基本能把 90% 的手势问题挡在提测之前。

从那以后我每次接列表交互需求，都会先把ItemTouchHelper的回调顺序和translationX复位这两件事写成检查项，跑一遍再谈 UI 细节。希望帮到你。

本文还有配套的精品资源，点击获取