Android RecyclerView 侧滑删除与长按拖拽：ItemTouchHelper 统一回调实战

简介：这份资源面向具备一定 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 动画绘制等环节展开，并涉及 LinearLayoutManager 与 GridLayoutManager 下的拖放处理。已有 371 人学习，适合想弄清侧滑删除、拖动排序底层实现并动手改造的读者参考。

1. 侧滑删除和长按拖拽，其实共用同一套回调

列表页里最容易被用户当成“标配”的两个交互，一个是左滑露出删除按钮，一个是长按把条目拖到新位置。很多 Android 项目在这两件事上各写一套手势监听，代码越堆越乱，滑动冲突、复用错位、数据不同步的问题轮番出现。这个项目走的是另一条路：用 RecyclerView 配合 ItemTouchHelper，把侧滑和拖拽收敛到同一个 Callback 里，让手势识别、动画绘制、数据落位都由系统组件接管。技术栈是标准的 Android Java 加 AndroidX RecyclerView，没有引入第三方手势库，适合正在做列表交互、想把这套机制吃透的开发者，也适合接手老项目、需要把散落的手势代码收拢的人。

2. 项目骨架与依赖：一个能跑的最小 RecyclerView 工程

2.1 目录结构与模块职责

这个项目的结构不复杂，属于典型的单模块 App 工程，重点全在列表相关的几个类上。把目录摊开看，职责划分是清楚的：

app/ ├── src/main/java/com/example/swipedrag/ │ ├── MainActivity.java // 入口，装配 RecyclerView 与 ItemTouchHelper │ ├── adapter/ │ │ └── ItemAdapter.java // 列表适配器，持有数据源 │ ├── model/ │ │ └── ItemBean.java // 条目数据模型 │ └── helper/ │ └── SwipeDragCallback.java // 核心：继承 ItemTouchHelper.Callback ├── src/main/res/ │ ├── layout/ │ │ ├── activity_main.xml // 只放一个 RecyclerView │ │ └── item_list.xml // 单条目布局 │ └── values/ │ └── strings.xml └── build.gradle

MainActivity只做装配，不掺业务逻辑；ItemAdapter管数据和 ViewHolder；真正的手势逻辑全部压在SwipeDragCallback里。这种拆法的好处是，以后要换交互方式，只动 Callback，适配器和布局不用碰。我一般接手列表类需求时，第一件事就是看手势逻辑有没有和 Adapter 搅在一起，搅在一起的基本都要返工。

2.2 依赖配置与版本约束

工程用的是 AndroidX，RecyclerView 是核心依赖，ItemTouchHelper 本身就在recyclerview包里，不需要额外引库。build.gradle里关键几行是这样：

android { compileSdk 34 defaultConfig { minSdk 21 targetSdk 34 } } dependencies { // ItemTouchHelper 随 RecyclerView 一起提供，无需单独依赖 implementation 'androidx.recyclerview:recyclerview:1.3.2' implementation 'androidx.appcompat:appcompat:1.6.1' implementation 'com.google.android.material:material:1.11.0' }

minSdk 21是个稳妥的起点，ItemTouchHelper 从 support 库时代就存在，API 21 以上行为一致，不用做版本分支。recyclerview的版本建议锁在 1.3.x，1.2 之前某些版本在onChildDraw的dX计算上有细微差异，跨版本调试容易怀疑人生。这里没有用 Kotlin，纯 Java 写法对老项目迁移更友好，也方便直接对照源码。

2.3 布局文件：两个 XML 就够

activity_main.xml极简，一个占满屏幕的 RecyclerView：

<androidx.recyclerview.widget.RecyclerView xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/recycler_view" android:layout_width="match_parent" android:layout_height="match_parent" android:clipToPadding="false" android:padding="8dp" />

clipToPadding="false"是为了让条目滑动时不被 padding 裁掉，侧滑动画在边缘更自然。单条目item_list.xml里放一个 TextView 加一个背景容器即可，重点是容器要有可辨识的背景色，否则侧滑时露出的底色和条目混在一起，用户根本看不出滑了多少。这些细节不影响功能跑通，但直接影响手感，属于上线前必须调的部分。

3. 核心机制拆解：ItemTouchHelper.Callback 的五个关键回调

3.1 手势方向声明：getMovementFlags 与 makeMovementFlags

ItemTouchHelper 靠getMovementFlags决定一个条目能往哪些方向动。侧滑和拖拽的方向都在这里声明，写错一个标志位，对应的手势就完全不响应：

@Override public int getMovementFlags(@NonNull RecyclerView recyclerView, @NonNull RecyclerView.ViewHolder viewHolder) { // 拖拽：允许上下移动（线性列表的典型配置） int dragFlags = ItemTouchHelper.UP | ItemTouchHelper.DOWN; // 侧滑：只允许从右往左滑，避免和返回手势冲突 int swipeFlags = ItemTouchHelper.LEFT; return makeMovementFlags(dragFlags, swipeFlags); }

makeMovementFlags(dragFlags, swipeFlags)把两个方向掩码打包成一个 int，内部做了位移编码，不要自己拼。这里只开LEFT是有意为之：右滑在很多机型上会和系统返回手势打架，用户滑一下列表直接退出页面，体验很糟。如果产品坚持要双向滑，把ItemTouchHelper.RIGHT也或进去，但要在onChildDraw里对两个方向分别处理背景色，否则左右滑看起来一模一样。

3.2 拖拽落位：onMove 里必须同步数据源

拖拽最容易翻车的地方不是动画，是数据。onMove只负责告诉你“第 from 个想挪到第 to 个”，真正交换数据的动作得自己做：

@Override public boolean onMove(@NonNull RecyclerView recyclerView, @NonNull RecyclerView.ViewHolder viewHolder, @NonNull RecyclerView.ViewHolder target) { int fromPos = viewHolder.getBindingAdapterPosition(); int toPos = target.getBindingAdapterPosition(); // 边界保护：位置无效时直接拒绝，避免 IndexOutOfBounds if (fromPos == RecyclerView.NO_POSITION || toPos == RecyclerView.NO_POSITION) { return false; } // 数据源交换 + 通知局部刷新，二者必须成对出现 Collections.swap(mDataList, fromPos, toPos); adapter.notifyItemMoved(fromPos, toPos); return true; }

三个点值得说清。第一，用getBindingAdapterPosition()而不是getAdapterPosition()，后者在有嵌套适配器或动画进行中可能返回NO_POSITION，前者更稳。第二，Collections.swap和notifyItemMoved必须成对，只换数据不通知，界面不动；只通知不换数据，下次拖拽位置全乱。第三，返回true表示这次移动被接受，返回false条目会弹回原位，边界保护那行就是靠这个兜底。我见过有人在这里直接return true不换数据，结果拖完看着动了，一刷新全回原样，排查半天以为是动画问题。

3.3 侧滑删除：onSwiped 的删除时机

侧滑划走之后，onSwiped被调用，这是真正删数据的入口：

@Override public void onSwiped(@NonNull RecyclerView.ViewHolder viewHolder, int direction) { int position = viewHolder.getBindingAdapterPosition(); if (position == RecyclerView.NO_POSITION) { return; } // 先移除数据，再通知；顺序反了会短暂出现空条目 mDataList.remove(position); adapter.notifyItemRemoved(position); // 删除后刷新后续条目的位置，防止复用错位 adapter.notifyItemRangeChanged(position, mDataList.size() - position); }

notifyItemRemoved只告诉 RecyclerView 少了一个，后面条目的 position 需要notifyItemRangeChanged补一刀，否则被删位置之后的条目绑定数据时拿到的还是旧 position，点击事件会错位到相邻项。这是侧滑删除最经典的坑，现象是“删了第三条，点第四条却打开了第三条的详情”。如果项目里带了撤销功能，删除动作应该先入一个待撤销队列，等 Snackbar 消失再真正落库，这里为了聚焦手势机制没有展开，二次开发时可以自己加。

3.4 滑动阈值与动画：onChildDraw 控制露出比例

默认的侧滑是整条跟着手指走，松手按阈值判定是否删除。想让滑动更“跟手”，可以重写onChildDraw调整位移比例：

@Override public void onChildDraw(@NonNull Canvas c, @NonNull RecyclerView recyclerView, @NonNull RecyclerView.ViewHolder viewHolder, float dX, float dY, int actionState, boolean isCurrentlyActive) { if (actionState == ItemTouchHelper.ACTION_STATE_SWIPE) { // 阻尼系数 0.5：手指滑 100px，条目只移 50px，滑起来更有分量 float damping = 0.5f; super.onChildDraw(c, recyclerView, viewHolder, dX * damping, dY, actionState, isCurrentlyActive); } else { super.onChildDraw(c, recyclerView, viewHolder, dX, dY, actionState, isCurrentlyActive); } }

dX是当前水平位移，负值代表左滑。乘一个小于 1 的系数做阻尼，视觉上条目“拽不动”，用户会更谨慎地滑，误删率明显下降。注意只对ACTION_STATE_SWIPE生效，拖拽状态不能加阻尼，否则上下拖动会变得黏滞。阈值本身由getSwipeThreshold控制，默认 0.5，意思是滑过条目宽度一半才触发删除，想更灵敏就调到 0.3，想更保守调到 0.7，按产品调性来。

3.5 长按拖拽的触发与视觉反馈

拖拽默认靠长按触发，isLongPressDragEnabled返回true即可。但光能拖还不够，拖起来得让用户知道“这个条目被拎起来了”：

@Override public void onSelectedChanged(RecyclerView.ViewHolder viewHolder, int actionState) { super.onSelectedChanged(viewHolder, actionState); if (actionState == ItemTouchHelper.ACTION_STATE_DRAG && viewHolder != null) { // 拖拽态：放大 + 加阴影，制造“浮起”感 viewHolder.itemView.setScaleX(1.05f); viewHolder.itemView.setScaleY(1.05f); viewHolder.itemView.setElevation(8f); } } @Override public void clearView(@NonNull RecyclerView recyclerView, @NonNull RecyclerView.ViewHolder viewHolder) { super.clearView(recyclerView, viewHolder); // 松手必须复位，否则复用后其他条目会带着放大态 viewHolder.itemView.setScaleX(1f); viewHolder.itemView.setScaleY(1f); viewHolder.itemView.setElevation(0f); }

onSelectedChanged在条目被选中（拖拽或侧滑开始）时回调，clearView在手势结束时回调。这两个方法必须成对写复位逻辑，因为 ViewHolder 是复用的，拖拽时放大的那个 View 滚出屏幕后可能被拿去显示别的条目，不复位就会看到“莫名其妙变大的列表项”。这是复用机制下的血泪经验，第一次遇到会以为是渲染 bug。

4. 装配与运行：把 Callback 挂到 RecyclerView 上

4.1 MainActivity 里的三行装配代码

核心逻辑写完后，装配只有三步：建适配器、设 LayoutManager、挂 ItemTouchHelper：

public class MainActivity extends AppCompatActivity { private final List<ItemBean> mDataList = new ArrayList<>(); @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); RecyclerView recyclerView = findViewById(R.id.recycler_view); // 1. 初始化数据 initData(); // 2. 装配适配器与布局管理器 ItemAdapter adapter = new ItemAdapter(mDataList); recyclerView.setLayoutManager(new LinearLayoutManager(this)); recyclerView.setAdapter(adapter); // 3. 挂载 ItemTouchHelper，Callback 持有数据源引用 SwipeDragCallback callback = new SwipeDragCallback(mDataList, adapter); new ItemTouchHelper(callback).attachToRecyclerView(recyclerView); } private void initData() { for (int i = 0; i < 20; i++) { mDataList.add(new ItemBean("条目 " + (i + 1))); } } }

attachToRecyclerView是唯一的挂载入口，传null可以解绑。Callback 构造时把mDataList和adapter传进去，是因为onMove和onSwiped需要同时操作数据和通知刷新，让 Callback 持有这两个引用比在回调里强转recyclerView.getAdapter()更直接，也避免了类型转换异常。数据量给 20 条是为了能滚动，验证拖拽到屏幕边缘时列表自动滚动的行为。

4.2 编译运行与真机验证清单

工程用 Android Studio 直接打开，Gradle 同步后连真机或模拟器运行即可，没有服务端依赖，也没有需要申请的运行时权限。跑起来之后按下面几项逐一验证，能覆盖大部分实现问题：

最后一项最容易暴露notifyItemRangeChanged漏写的问题。模拟器上跑没问题不代表真机没问题，侧滑手势和系统返回手势的冲突建议在真机上验证，模拟器没有系统手势区，测不出来。

4.3 数据模型与适配器的配合

ItemBean只需要一个展示字段，ItemAdapter继承RecyclerView.Adapter，在onBindViewHolder里绑定文本。这里有个容易忽略的点：适配器的数据源引用必须和 Callback 操作的是同一个 List 实例。如果 Adapter 内部做了new ArrayList<>(data)拷贝，Callback 里 swap 的是原列表，界面绑定的却是拷贝，拖拽就会“动了但没完全动”。常见做法是构造时直接持有引用，不拷贝，并在注释里写清楚这个约定，避免后来者顺手加个防御性拷贝把功能搞坏。

5. 避坑与排查：五个真实踩过的坑

5.1 拖拽后点击错位

现象：拖拽调整顺序后，点击某个条目，打开的是另一个条目的内容。原因：onMove里只调了notifyItemMoved，没有同步交换数据源，或者交换了数据但 Adapter 持有的是另一个 List 实例。解决：确认Collections.swap和notifyItemMoved成对出现，且 Callback 与 Adapter 引用同一个 List；在onBindViewHolder里打日志打印 position 和条目内容，一眼就能看出绑定错位。

5.2 侧滑删除后列表出现空白项

现象：连续删除几条后，列表中间出现空白，或者最后一条重复显示。原因：onSwiped里只调了notifyItemRemoved，没有对后续条目做notifyItemRangeChanged，被删位置之后的 ViewHolder 还带着旧 position。解决：删除后补一行notifyItemRangeChanged(position, mDataList.size() - position)；如果用了 DiffUtil，改用submitList走差分更新，能彻底规避这类手动通知的遗漏。

5.3 拖拽放大的条目“传染”给其他项

现象：拖拽某条目后，滚动列表，发现别的条目也变大了。原因：onSelectedChanged里设置了setScaleX/Y，但clearView里没复位，ViewHolder 复用时把放大态带到了新数据上。解决：clearView里把所有在onSelectedChanged改过的属性逐一复位，包括缩放、阴影、背景色；更稳的做法是把这些视觉状态写进 ViewHolder 的绑定逻辑，每次绑定都重置一遍。

5.4 侧滑和系统返回手势冲突

现象：在全面屏机型上，从屏幕左边缘右滑想返回，结果列表条目跟着动，或者反过来。原因：getMovementFlags里开了ItemTouchHelper.RIGHT，和系统边缘手势区重叠。解决：只开LEFT单向侧滑；如果产品必须双向，在onChildDraw里判断起始触摸点是否落在边缘手势区内，落在区内就不响应，或者干脆把侧滑方向改成从右往左，避开返回手势的主战场。

5.5 拖拽到列表边缘不自动滚动

现象：长按拖到屏幕顶部或底部，列表不跟着滚，没法把条目拖到很远的位置。原因：ItemTouchHelper 的自动滚动依赖 RecyclerView 的滚动能力，如果外层套了NestedScrollView或者 RecyclerView 高度被约束成wrap_content，滚动就失效。解决：确保 RecyclerView 高度是match_parent或固定值，不要嵌在可滚动父容器里；如果业务上必须嵌套，给 RecyclerView 设置setNestedScrollingEnabled(true)并检查父容器的滚动拦截逻辑。

6. 二次开发：把回调抽成可配置的手势策略

这套代码跑通之后，真正花时间的是把它改造成能适应不同列表需求的样子。我的做法是把SwipeDragCallback从“写死方向”改成“构造时注入策略”，让同一个 Callback 类服务多种列表：

public class SwipeDragCallback extends ItemTouchHelper.Callback { private final List<ItemBean> data; private final ItemAdapter adapter; private final boolean dragEnabled; // 是否允许拖拽排序 private final boolean swipeEnabled; // 是否允许侧滑删除 public SwipeDragCallback(List<ItemBean> data, ItemAdapter adapter, boolean dragEnabled, boolean swipeEnabled) { this.data = data; this.adapter = adapter; this.dragEnabled = dragEnabled; this.swipeEnabled = swipeEnabled; } @Override public int getMovementFlags(@NonNull RecyclerView rv, @NonNull RecyclerView.ViewHolder vh) { int dragFlags = dragEnabled ? ItemTouchHelper.UP | ItemTouchHelper.DOWN : 0; int swipeFlags = swipeEnabled ? ItemTouchHelper.LEFT : 0; return makeMovementFlags(dragFlags, swipeFlags); } }

方向掩码传 0 就等于禁用对应手势，不用再写两个 Callback 子类。改造之后，一个“只读列表”传false, false，一个“可排序不可删”传true, false，配置在 Activity 里一眼可见，比在回调内部写 if-else 判断列表类型干净得多。

验证改造是否成功，我习惯用三个动作走一遍：先拖一条到列表末尾再拖回来，确认数据顺序和界面一致；再侧滑删一条，点一下相邻条目确认没错位；最后快速连续删三条，看有没有空白项。这三步能覆盖数据同步、位置刷新、复用复位三个最容易出问题的环节。

还有一个值得做的扩展是给侧滑加“撤销”。onSwiped里不直接remove，而是把条目和原位置存进一个栈，弹 Snackbar，用户点撤销就插回去并notifyItemInserted。这里的关键是撤销时要用原位置而不是末尾位置，否则顺序会乱，我一般会在栈里存(position, item)二元组，插入前先做一次边界钳制，防止原位置已经越界。

从那以后我每次接列表交互需求，都强制先把onMove和onSwiped的数据同步逻辑单独跑一遍再往上叠 UI，因为这两个回调里的数据错位一旦混进业务代码，排查成本会翻好几倍。希望这套拆解能帮到你，把侧滑拖拽这块从“能跑”推到“敢改”。

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