简介Android开发中RecyclerView结合ItemTouchHelper实现侧滑拖拽是高频交互需求。这份资源正是一套可直接运行的工程Demo面向具备一定Android基础、希望掌握列表项滑动删除与拖拽排序的开发者。压缩包共44个文件核心为13个XML布局与11个Java源码另含Gradle构建配置、属性文件及运行脚本支持直接导入Android Studio调试。资源内提供完整的demo-ui工程并附带《RecyclerView侧滑源码解析》文档清晰拆解ItemTouchHelper.Callback中onMove、onSwiped等关键回调以及notifyItemMoved、notifyItemRangeChanged等刷新与动画处理细节便于对照实际代码理解实现原理。全包仅763KB轻量实用。已有369人学习下载适合用于日常开发实战参考也可作为教学案例快速帮助开发者建立事件处理、数据绑定与UI更新闭环的完整认知。1. 先搞清楚需求与方案选型做安卓开发这几年RecyclerView 几乎天天见但真正把侧滑删除、长按拖拽这些交互做得顺手的项目其实不算多。很多同学一上来就自己重写 onTouchEvent在 Adapter 里存 position、监听 ACTION_MOVE结果不是列表滚动卡顿就是 item 之间动画错乱。其实系统早就给了一套标准方案——ItemTouchHelper。这东西是 support 包现在叫 androidx.recyclerview里的官方工具类专门用来处理 item 的拖拽、滑动和侧滑删除最大的优势是它完整接管了触摸事件和动画你只需要在 Callback 里声明“哪些方向可以滑、哪些方向可以拖”剩下的位移、回弹、删除动画它全包了。先明确一点ItemTouchHelper 不是 RecyclerView 的默认能力它需要你手动 new 出来然后 attach 到 RecyclerView 上。整个过程核心就两件事一是自定义一个 Callback 继承 ItemTouchHelper.Callback告诉它拖拽滑动的规则二是用 ItemTouchHelper.attachToRecyclerView 完成绑定。很多人卡在第一步就懵了——Callback 里有十几个方法到底哪些必须实现哪些可以不写其实你真正常写的通常只有三四个其他的基本都是空实现今天我按实操顺序把整个流程捋一遍。这个方案的适用范围也说明一下它适合所有需要列表项可拖动排序、可滑动删除的场景。典型的有任务清单 App 的拖动排序、消息列表的侧滑删除、购物车商品长按调整顺序、后台管理列表的手势操作等。我接下来讲的内容基于 androidx.recyclerview:recyclerview:1.3.x 的稳定版本Kotlin 为例Java 的写法也就是换成匿名内部类而已思路完全一样。2. 核心回调逐行拆解2.1 getMovementFlags告诉系统哪些方向能拖、能滑先看最关键的方法 getMovementFlags它决定了一个 item 在哪些方向可以响应手势。返回值是一个 int 类型的 flags用 makeMovementFlags(dragFlags, swipeFlags) 来拼。这里有两个坑要提前说第一要区分 dragFlags 和 swipeFlags 分别代表的内容不要混第二很多人以为只有水平滑动才叫“拖拽”其实拖拽指的是 item 在列表中换位置的移动侧滑删除则是 item 被滑出屏幕外的操作。具体到我们常见的交互——列表项可以长按上下拖动换位置同时可以左右侧滑删除。写成代码就是下面这样override fun getMovementFlags( recyclerView: RecyclerView, viewHolder: RecyclerView.ViewHolder ): Int { // 支持上下拖拽换位置 val dragFlags ItemTouchHelper.UP or ItemTouchHelper.DOWN // 支持左右侧滑 val swipeFlags ItemTouchHelper.LEFT or ItemTouchHelper.RIGHT return makeMovementFlags(dragFlags, swipeFlags) }如果你只需要侧滑删除不需要拖拽排序那就把 dragFlags 设为 0。如果你只想上下拖动不想侧滑删除那就把 swipeFlags 设为 0。这里有一点容易踩坑dragFlags 为 0 时onMove 方法不会被回调swipeFlags 为 0 时onSwiped 不会被回调。很多同学写完代码发现某个手势没反应多半就是 flags 没有配对。2.2 onMove 与 onSwiped动作的落点处理接下来是实际发生数据变化的地方。onMove 是用户在拖拽过程中触发的它会在“手指按住一个 item 移到另一个 item 的位置”时被回调。注意它的触发频率非常高onMove 是一个可以一直回调的方法你要在里面做的核心操作是把数据源里对应项的位置换过去然后调用 notifyItemMoved 刷新。我见过不少新手的写法是拖拽过程中在 onMove 里频繁调用 adapter.notifyDataSetChanged()——这是大忌。列表项少还好一旦数据几十条以上你会明显感觉到卡顿而且动画会失效。正确的姿势是用 Collections.swap 交换两个位置的数据然后 notifyItemMoved它能精确触发 item 的平移动画。override fun onMove( recyclerView: RecyclerView, viewHolder: RecyclerView.ViewHolder, target: RecyclerView.ViewHolder ): Boolean { val fromPosition viewHolder.bindingAdapterPosition val toPosition target.bindingAdapterPosition if (fromPosition 0 || toPosition 0 || fromPosition dataList.size || toPosition dataList.size) { return false } Collections.swap(dataList, fromPosition, toPosition) adapter.notifyItemMoved(fromPosition, toPosition) return true }注意上面代码里用了 bindingAdapterPosition 而不是 getAdapterPosition()旧方法在异步刷新场景下可能返回 RecyclerView.NO_POSITION新版中官方已经建议用 bindingAdapterPosition 或 absoluteAdapterPosition。这算是一个新版 API 的小坑后面排查问题部分我再细说。onSwiped 则是侧滑结束时的回调。它传入的 direction 告诉你滑动的方向你在这里把数据从列表里移除然后通知 adapter 删除这一项。删除动画其实由 ItemTouchHelper 内部接管你只需要处理数据源和刷新即可。override fun onSwiped(viewHolder: RecyclerView.ViewHolder, direction: Int) { val position viewHolder.bindingAdapterPosition if (position 0 || position dataList.size) { return } dataList.removeAt(position) adapter.notifyItemRemoved(position) }有个细节很多人忽略了onSwiped 触发后item 已经滑出屏幕视觉范围但数据还没移除的时候RecyclerView 的缓存机制会比较敏感。如果你在 onSwiped 里直接操作了数据源又调用 notifyItemRemoved通常没问题但如果你同时调用了多个 item 的删除必须保证数据源和 notify 的次数一一对应否则会崩溃。后面我会给一个批量删除的坑。2.3 isLongPressDragEnabled 与 isItemViewSwipeEnabled交互开关这两个方法决定了交互的入口。isLongPressDragEnabled 默认返回 true意思是“长按某个 item 就能开始拖拽”如果你不想让所有 item 都支持长按拖拽可以返回 false然后通过 startDrag(viewHolder) 主动开启拖拽。androidx 提供了一个 ViewHolder 的方法在 itemView 的长按事件里调用// 只允许某个按钮触发拖拽 holder.itemView.findViewByIdView(R.id.iv_drag).setOnLongClickListener { itemTouchHelper.startDrag(holder) true }这个方式能实现“只有拖动图标才能拖拽”的常见交互。要注意的是startDrag 必须在 item 还未被 RecyclerView 复用之前调用所以一般放在 ViewHolder 的控件事件里才稳。isItemViewSwipeEnabled 默认返回 true意思是允许侧滑。如果你只在某个特定条件下允许侧滑可以在这里做判断。这个开关是全局性的不要在它里面根据 position 判断因为它是拿不到当前滑动的 item 的。3. 完整实操从零写一个侧滑拖拽列表3.1 布局与 ViewHolder 准备先说一下最基本的例子。布局用最简单的 LinearLayoutRecyclerView 占满全屏。item 布局就是一个横向排列的文本和图标为了演示拖动效果我给每个 item 左侧加了一个拖拽图标右侧是一个 TextView。图标选中监听长按文本本身不响应长按。实际项目中建议不要使用 android:clickablefalse 这种做法去规避触摸冲突后面我会专门讲触摸事件冲突的处理。ViewHolder 的代码很简单就是标准的绑定加监听。这里我要多嘴一句很多人习惯在 ViewHolder 的 bind 里写一个接口回调往 Activity 或 Fragment 传事件这是可以的但如果是高度封装的列表更推荐直接用监听器接口放到 Adapter 层级方便后续结合 ViewModel 做事件流。3.2 编写 ItemTouchHelper.Callback 子类回调子类是核心代码我平时都是一个独立的文件放一个类成员变量主要包括起点位置、数据源引用、拖拽开关等。这里列一个完整可用的 Kotlin 版class SwipeDragCallback( private val dataList: MutableListTaskBean, private val adapter: RecyclerView.Adapter* ) : ItemTouchHelper.Callback() { override fun getMovementFlags( recyclerView: RecyclerView, viewHolder: RecyclerView.ViewHolder ): Int { val dragFlags ItemTouchHelper.UP or ItemTouchHelper.DOWN val swipeFlags ItemTouchHelper.LEFT or ItemTouchHelper.RIGHT return makeMovementFlags(dragFlags, swipeFlags) } override fun onMove( recyclerView: RecyclerView, viewHolder: RecyclerView.ViewHolder, target: RecyclerView.ViewHolder ): Boolean { val from viewHolder.bindingAdapterPosition val to target.bindingAdapterPosition if (from 0 || to 0 || from dataList.size || to dataList.size) { return false } Collections.swap(dataList, from, to) adapter.notifyItemMoved(from, to) return true } override fun onSwiped(viewHolder: RecyclerView.ViewHolder, direction: Int) { val position viewHolder.bindingAdapterPosition if (position 0 || position dataList.size) { return } dataList.removeAt(position) adapter.notifyItemRemoved(position) } override fun clearView(recyclerView: RecyclerView, viewHolder: RecyclerView.ViewHolder) { super.clearView(recyclerView, viewHolder) viewHolder.itemView.alpha 1f viewHolder.itemView.scaleX 1f viewHolder.itemView.scaleY 1f } override fun onSelectedChanged(viewHolder: RecyclerView.ViewHolder?, action: Int) { super.onSelectedChanged(viewHolder, action) if (action ! ItemTouchHelper.ACTION_STATE_IDLE) { viewHolder?.itemView?.alpha 0.7f viewHolder?.itemView?.scaleX 0.95f viewHolder?.itemView?.scaleY 0.95f } } }这段代码里有两个值得注意的点。onSelectedChanged 是在 item 进入或退出“被选中”状态时回调的。当进入拖拽或滑动状态时action 会变成 ACTION_STATE_DRAG 或 ACTION_STATE_SWIPE我在这里把 item 缩小加透明给用户明确反馈。clearView 则是在动画结束后回调我把状态恢复成正常。很多教程只写了拖动逻辑没处理状态反馈用户体验差一截但实际上只需要几行代码就能做得很自然。3.3 在 Activity/Fragment 中绑定并启用然后就是在界面里初始化val itemTouchHelper ItemTouchHelper(SwipeDragCallback(dataList, adapter)) itemTouchHelper.attachToRecyclerView(binding.recyclerView)这里的顺序有讲究必须先把 RecyclerView 的设置完成LayoutManager、Adapter再 attachToRecyclerView。如果在 setAdapter 之前 attachItemTouchHelper 内部有可能拿不到有效的 Adapter虽然不会崩溃但手势处理不会生效。另外如果你用的是 DiffUtil 而不是 notifyDataSetChanged那么 onSwiped 里的数据结构要小心DiffUtil 会把移动和删除识别成不同的 payload如果你在删除数据的同时调用了 notifyItemRemoved而其他地方又对数据源做了整合可能引发 “IndexOutOfBoundsException: Inconsistency detected”。最稳妥的方案是数据和刷新操作始终保持在同一个事务里不要跨线程修改列表。布局文件里我给 RecyclerView 设了 android:overScrollModenever避免滑动删除时出现拉伸回弹效果干扰视觉。这只是体验层面的优化不是必须。3.4 侧滑背景与按钮的扩展处理基础功能跑通之后我们往往会遇到产品需求侧滑的时候要露出一个“删除”按钮甚至左侧还有个“置顶”按钮。ItemTouchHelper 本身不提供布局但可以借助 CustomView 实现。常见的思路有两种一种是在 item 底部放一个按钮层默认隐藏在 itemView 下面侧滑时 itemView 移动露出下面的按钮另一种是自己监听滑动位移实时控制按钮的显示。前者实现简单推荐优先尝试。具体做法是item 根布局用一个 FrameLayout里面先放一个水平 LinearLayout 的按钮层再放一个 itemView 作为上层。ItemTouchHelper 滑动时移动的是整个上层 view底层按钮自然露出来。当你点击底层按钮时再通过 adapter 的接口回调处理删除逻辑同时注意别让滑动删除的 onSwiped 重复触发。这里有个小细节你的自定义 ViewHolder 的 itemView 不能是整个 FrameLayout而是 FrameLayout 里的那个上层内容布局这样侧滑时才不会连按钮一起滑走。4. 常见问题与排查技巧实录4.1 长按拖拽为什么没反应这是频率最高的问题。排查顺序我建议这样先看 getMovementFlags 的 dragFlags 是不是为 0再看 isLongPressDragEnabled 是否被改回了 false最后检查 itemView 有没有设置 clickable 或 focusable。第三种坑是因为 RecyclerView 的 item 如果有内层控件获取了焦点长按事件被内层消费掉ItemTouchHelper 收不到。解决办法是在 itemView 根布局或拖拽按钮上设置 onClickListener让触摸事件能被父级拦截或者把内层控件的 clickable 改掉。另外提一个经常被忽略的点如果列表设置了 NestedScrollView 嵌套长按拖拽极容易失效。因为 NestedScrollView 会拦截触摸事件ItemTouchHelper 拿不到滑动序列。解决方案是优先使用普通的 ScrollView 或者干脆不用嵌套如果一定要嵌套可以重写 NestedScrollView 的 onInterceptTouchEvent但这属于特殊场景不展开说了。4.2 侧滑删除后列表错位或崩溃错位通常是数据源 position 和 item 实际位置不一致导致的。尤其是在 item 高度不一致的场景里position 会因为 notifyItemRemoved 后的布局计算延迟而产生偏差。这里我推荐在 onSwiped 和 onMove 里统一使用 bindingAdapterPosition并且每次都做边界判断。用 position 而不是 layoutPosition 也是同理adapterPosition 在异步刷新时可能变成 NO_POSITION而 -1 会导致 removeAt 崩溃。这也是为什么我在前面代码里写了很多 if 判断看似冗余实则保命。注意如果你在 onSwiped 里只调用了 adapter.notifyItemRemoved(dataList.size - 1)而数据源 removeAt 用的是另一个索引那基本必崩。务必保证 removeAt 的下标和 notifyItemRemoved 的下标来自同一个来源。批量删除的场景也补充一下。你可能会在 onSwiped 里判断同一个 holder 是否已被删除但更正确的做法是删除前先记录 position然后通过 adapter.submitList 或差量更新重新设置数据源。使用 ListAdapter 的项目尤其要注意因为 AsyncListDiffer 会根据 diff 结果自己刷新你在 onSwiped 里手动 notifyItemRemoved 会导致 diff 结果和当前数据不一致从而触发 IllegalStateException。4.3 侧滑后 item 没有回弹动画这种情况大概率是你在 clearView 里做了数据修改但没有通过 notify 刷新或者你在 onSwiped 时没有真正调用 removeAt导致数据源和界面状态不一致。如果 item 还在列表里但侧滑后停住了多半是 touchSlop 和默认动画被某个 setOnTouchListener 拦截了。检查一下你给 item 设置的 touch listener 是否调用了 onTouchEvent —— 一旦你消费了事件而不返回 falseItemTouchHelper 就无法接管后续手势。我排查这类问题常用一个笨但有效的办法给 callback 的 getMovementFlags、onSwiped、onMove 打 Log打印当前 holder 的位置、action、direction。这个办法比猜快得多我强烈建议你也试试。4.4 侧滑和点击事件冲突怎么办item 本身有点击事件侧滑的时候发现点击事件先触发了这是很多人的痛点。原因在于ItemTouchHelper 在开始滑动后到 swiped 完成之间会消费触摸事件但 itemView 上的 OnClickListener 是在 ACTION_UP 时触发的它可能抢在 ItemTouchHelper 的 ACTION_UP 之前执行。解决方式是在 onSelectedChanged 进入 ACTION_STATE_SWIPE 时标记一个全局变量 allowClick false在 ACTION_STATE_IDLE 时再恢复为 true然后在 onBindViewHolder 的点击监听里判断这个标记。更简单的方式是给 itemView 设置一个 OnTouchListener在 ACTION_MOVE 且位移超过 touchSlop 后禁止后续 click 传递。这个冲突问题在设置了 isLongPressDragEnabled 时更隐蔽因为长按拖拽会让系统进入拖拽状态此时 OnLongClickListener 和 OnClickListener 可能同时被触发尤其是用户按住 item 超过几秒没动松手时容易误触发点击。我的处理习惯是进入拖拽状态时在 onSelectedChanged 中把 itemView 的 isEnabled 设为 falseclearView 时再恢复 true。4.5 删除后的底部 item 上浮动画不自然这个问题很多人遇到过视觉上表现为删除后下方 item 不是平滑“顶上去”而是跳动或者直接消失。原因通常是你在 onSwiped 中调用了 notifyDataSetChanged 而不是精确的位置刷新。你要用 notifyItemRemoved(position)而不是 notifyDataSetChanged。notifyItemRemoved 会触发 RecyclerView 的预测动画而 notifyDataSetChanged 会让整个列表重新绑定动画自然就没了。如果页面里还有其他逻辑导致这两者必须共存请务必控制好刷新范围把 removeAt 和 notifyItemRemoved 放在同一个同步代码块里。5. 调试技巧与其他经验小结调试这类手势交互最忌讳的就是文字上推演UI 的问题不亲眼看动画跑一遍很难定位。我的经验是准备一个调试开关在 Adapter 里放一个模拟数据的按钮随时添加随机 item专门用来验证拖拽和删除后的状态。这样你能快速复现“从 10 条删到 3 条后再拖拽”的边界情况。还要注意一个正则容易忽视的点如果列表里存在 header 或者 footer也就是多种 viewType 的 Adapter那么 getMovementFlags 里要对 viewHolder.getItemViewType() 做判断。头部和底部如果不该被拖拽或删除就返回 0。否则你会出现“明明设置了拖拽但 header 怎么也能拖”的怪现象。关于性能ItemTouchHelper 在 item 数量超过几百条时也能保持流畅因为它做的位移计算都是在动画线程里完成的没有额外创建 view。唯一的性能瓶颈在于你的 onMove 里调用了重量级操作比如 API 请求、数据库写操作那是你自己的问题不是 ItemTouchHelper 的锅。把数据持久化的逻辑放在 onSwiped 或 onMove 完成后的回调里用协程或者 Handler post 到子线程不要阻塞主线程。最后再分享一个小技巧如果想实现“左滑进入编辑状态右滑删除”这种不对称交互可以在 onSwiped 的 direction 里判断左滑时插入一条事件右滑时才删数据。通过返回不同的 flags 组合也能实现单侧滑动的限制把 swipeFlags 改为只允许 LEFT右侧收不到事件就自然无法滑。操作上完全可以利用这几个回调灵活组合满足产品五花八门的需求不用自己去写一套触摸捕获逻辑。我踩过几次坑之后的体会就是能用系统提供的成熟方案就别自己造轮子ItemTouchHelper 这套流程虽然方法多但真正需要关心的地方其实就是 flags、数据同步和状态反馈这三件事把这三件事处理干净列表手势交互基本就稳了。本文还有配套的精品资源点击获取