CardSwipeLayout使用指南:OnSwipeListener三大回调onSwiping、onSwiped、onSwipedClear全解析
CardSwipeLayout使用指南:OnSwipeListener三大回调onSwiping、onSwiped、onSwipedClear全解析
CardSwipeLayout 是一个基于 RecyclerView 的 Android 卡片滑动布局库,几行代码就能复刻探探同款"左右滑卡匹配"效果——滑走一张,后面的卡片自动顶上。它的交互逻辑全部由 OnSwipeListener 接口的三个回调驱动:onSwiping(滑动进行中)、onSwiped(单张滑出)、onSwipedClear(全部滑完)。读懂本文,你就能像探探一样做出"喜欢/跳过"反馈、数据移除与加载更多。
🃏 先认识一下 CardSwipeLayout 卡片滑动效果
多张卡片叠放在一起(默认同屏显示 3 张),只有最上面的卡片响应触摸;向左或向右滑出屏幕后,后面的卡片自动"顶上"。滑动过程中卡片会跟随手指倾斜,后面的卡片同步"冒前",这正是匹配动效的核心。
三个核心类各司其职:
| 类 | 职责 |
|---|---|
| CardLayoutManager.java | 管理卡片堆叠布局,只给最上层卡片绑定触摸 |
| CardItemTouchHelperCallback.java | 处理滑动手势与旋转/冒前动画,负责触发回调 |
| OnSwipeListener.java | 回调接口,定义了本文主角三大回调 |
🚀 三步快速接入 CardSwipeLayout
先在 build.gradle 添加依赖:
compile 'me.yuqirong:cardswipelayout:1.0.0'
然后三步完成接入(前提是 RecyclerView 已设置好 Adapter):
// ① 创建回调,传入 Adapter 和数据源
CardItemTouchHelperCallback cardCallback =
new CardItemTouchHelperCallback(recyclerView.getAdapter(), dataList);
// ② 接入布局管理器与触摸助手
ItemTouchHelper touchHelper = new ItemTouchHelper(cardCallback);
recyclerView.setLayoutManager(new CardLayoutManager(recyclerView, touchHelper));
touchHelper.attachToRecyclerView(recyclerView);
// ③ 注册 OnSwipeListener 监听器(本文重点)
cardCallback.setOnSwipedListener(new OnSwipeListener<T>() { /* ... */ });
💡 也可以在构造
CardItemTouchHelperCallback时直接传入监听器,效果相同。
🔍 OnSwipeListener 三大回调全解析
接口定义非常短,三个方法都需要实现:
public interface OnSwipeListener<T> {
void onSwiping(RecyclerView.ViewHolder viewHolder, float ratio, int direction);
void onSwiped(RecyclerView.ViewHolder viewHolder, T t, int direction);
void onSwipedClear();
}
1️⃣ onSwiping:卡片滑动过程中的实时进度回调
触发时机:滑动持续期间反复触发、几乎逐帧回调,触发点位于 onChildDraw 方法。
参数说明:
| 参数 | 含义 |
|---|---|
viewHolder |
当前正在滑动的卡片 ViewHolder |
ratio |
滑动进度,取值 [-1, 1];负值向左、正值向右,绝对值越大滑得越远 |
direction |
滑动方向常量,见下表 |
方向常量定义在 CardConfig.java:
| 常量 | 含义 |
|---|---|
CardConfig.SWIPING_LEFT |
正在向左滑 |
CardConfig.SWIPING_RIGHT |
正在向右滑 |
CardConfig.SWIPING_NONE |
不偏左也不偏右(如 ratio 为 0 时) |
典型用法:ratio 逐帧变化,是做进度联动动画的完美素材。示例 App 用它实现"右滑淡入点赞图标、左滑淡入跳过图标"(代码来自 MainActivity.java):
@Override
public void onSwiping(RecyclerView.ViewHolder viewHolder, float ratio, int direction) {
MyViewHolder myHolder = (MyViewHolder) viewHolder;
viewHolder.itemView.setAlpha(1 - Math.abs(ratio) * 0.2f);
if (direction == CardConfig.SWIPING_LEFT) {
myHolder.dislikeImageView.setAlpha(Math.abs(ratio)); // 左滑淡入"跳过"
} else if (direction == CardConfig.SWIPING_RIGHT) {
myHolder.likeImageView.setAlpha(Math.abs(ratio)); // 右滑淡入"点赞"
} else {
// SWIPING_NONE:把两个图标重置为透明
myHolder.dislikeImageView.setAlpha(0f);
myHolder.likeImageView.setAlpha(0f);
}
}
2️⃣ onSwiped:卡片完全滑出屏幕时的回调
触发时机:卡片完全滑出屏幕后,库先从数据源移除数据、再触发回调,实现位于 onSwiped 方法。
参数说明:
| 参数 | 含义 |
|---|---|
viewHolder |
滑出卡片的 ViewHolder |
t |
已从数据源移除的这条数据(泛型 T,即你数据源里的元素类型) |
direction |
SWIPED_LEFT 表示左侧滑出,SWIPED_RIGHT 表示右侧滑出 |
典型用法:这是做业务决策的时机——发起"喜欢"请求、记录匹配结果,并重置上一阶段的动画状态:
@Override
public void onSwiped(RecyclerView.ViewHolder viewHolder, T item, int direction) {
// 重置上一步留下的透明度变化,为 ViewHolder 复用做准备
viewHolder.itemView.setAlpha(1f);
if (direction == CardConfig.SWIPED_RIGHT) {
// 向右滑出 = "喜欢",可向服务器发起请求,item 就是该卡片的数据
sendLikeRequest(item);
}
}
⚠️ 重点提示:不要在这个回调里自己
remove数据!库在触发回调前已经执行了dataList.remove(...)和notifyDataSetChanged(),重复移除会引发下标越界或数据错位。
3️⃣ onSwipedClear:所有卡片全部滑完时的回调
触发时机:上一张卡片滑出后数据源已空(getItemCount() == 0),紧跟在 onSwiped 之后触发,逻辑见 CardItemTouchHelperCallback.java。
参数:无。
典型用法:加载更多数据,或展示"没有更多了"的空状态页:
@Override
public void onSwipedClear() {
// 所有卡片都滑完了:加载更多,或提示"没有更多数据"
loadNextPage();
}
示例 App 在这个回调里弹出 Toast 提示,并延迟 3 秒自动重新灌入数据,完整实现见 MainActivity.java。
📊 三大回调对照表
| 回调 | 触发时机 | 参数 | 触发频率 | 典型场景 |
|---|---|---|---|---|
onSwiping |
滑动过程中 | viewHolder / ratio / direction | 高(几乎逐帧) | 进度动画、图标淡入淡出 |
onSwiped |
单张卡片完全滑出 | viewHolder / 数据项 / direction | 每张卡片一次 | 发起"喜欢"请求、重置动画 |
onSwipedClear |
数据源滑空 | 无 | 数据耗尽一次 | 加载更多、空态展示 |
💡 实用技巧与常见坑
- 别忘了
SWIPING_NONE分支:手指竖直方向移动时ratio为0,direction 是SWIPING_NONE,可借机把卡片状态重置干净,避免"残留"。 onSwipedClear只在数据源空时触发:不是"每滑出一屏就触发一次",判断依据是getItemCount() == 0。- ViewHolder 会被 RecyclerView 复用:在
onSwiping里改过的 alpha 等属性,务必在onSwiped中重置,否则状态会污染下一张卡片。 - 方向常量分两套:
SWIPING_*系列描述"滑动中",SWIPED_*系列描述"已滑出",两者不要混用。
📁 模块路径速查
- 核心库源码:lib/src/main/java/me/yuqirong/cardswipelayout/
- 回调接口定义:OnSwipeListener.java
- 方向常量定义:CardConfig.java
- 滑动手势与动画逻辑:CardItemTouchHelperCallback.java
- 卡片堆叠布局:CardLayoutManager.java
- 示例 App(三大回调完整用例):MainActivity.java
- 示例卡片布局(点赞/跳过图标):item.xml
✅ 小结
OnSwipeListener 把卡片滑动的交互拆成了三个清晰的阶段:
- onSwiping ——"正在滑":做进度联动动画,如点赞图标淡入;
- onSwiped ——"滑出去了":执行业务操作(喜欢/跳过),并重置动画状态;
- onSwipedClear ——"全部滑完":加载更多或展示空态。
配合 DEFAULT_SHOW_ITEM(同屏 3 张)、DEFAULT_ROTATE_DEGREE(最大倾斜 15°)等默认参数,按上文三步接入并实现好三个回调,就能快速搭建出一个探探风格的卡片滑动匹配页面。