CardSwipeLayout使用指南:OnSwipeListener三大回调onSwiping、onSwiped、onSwipedClear全解析

原创2026-10-12 17:43:001,674 阅读

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_* 系列描述"已滑出",两者不要混用。

📁 模块路径速查

✅ 小结

OnSwipeListener 把卡片滑动的交互拆成了三个清晰的阶段:

  1. onSwiping ——"正在滑":做进度联动动画,如点赞图标淡入;
  2. onSwiped ——"滑出去了":执行业务操作(喜欢/跳过),并重置动画状态;
  3. onSwipedClear ——"全部滑完":加载更多或展示空态。

配合 DEFAULT_SHOW_ITEM(同屏 3 张)、DEFAULT_ROTATE_DEGREE(最大倾斜 15°)等默认参数,按上文三步接入并实现好三个回调,就能快速搭建出一个探探风格的卡片滑动匹配页面。

登录后查看全文
CardSwipeLayout