CardSwipeLayout项目全览:用3个核心类实现仿探探卡片滑动布局的开源利器

原创2026-10-12 17:11:451,633 阅读

CardSwipeLayout项目全览:用3个核心类实现仿探探卡片滑动布局的开源利器

CardSwipeLayout 是一个基于 Android RecyclerView 实现的仿探探卡片滑动布局轻量开源库,完整还原"左滑无感、右滑喜欢"的经典交互。整个库仅靠 3 个核心类、几乎零第三方依赖,新手 3 步即可完成集成,非常适合做卡片式推荐页的开发者上手。

✨ 它能做什么

特性 说明
卡片叠放 默认同屏 3 张卡片,后方卡片逐层缩小、下移,形成自然"牌堆"
卡片滑动 最前卡片随手势实时倾斜,松手后向左/向右飞出
联动动画 前卡滑走过程中,后方卡片自动"顶出"补位
回调钩子 滑动中 / 滑出 / 全部滑完 3 个回调,方便叠加淡入、加载等效果
许可证 MIT

🧩 3 个核心类:一个管叠、一个管滑、一个管回调

核心源码全部位于 lib/src/main/java/me/yuqirong/cardswipelayout/,共 4 个文件(3 个核心类 + 1 个参数常量类):

类 一句话职责
CardLayoutManager 自定义布局管理器,负责把卡片"叠"起来
CardItemTouchHelperCallback ItemTouchHelper 扩展,负责"滑"动、动画与数据移除
OnSwipeListener 回调接口,把滑动过程交给业务层定制
CardConfig 集中管理可见数、缩放比例、倾斜角等参数

三者形成一条链路:LayoutManager 摆放卡片并启动滑动手势 → ItemTouchHelper 处理滑动过程与画面 → OnSwipeListener 在关键节点通知业务层。

1️⃣ CardLayoutManager:让卡片"叠"起来

核心是 CardLayoutManager.java 中的 onLayoutChildren 重写:

  • 居中排布:卡片逐一在 RecyclerView 中居中
  • 逐层缩小:第二张卡片缩小 10%,之后每层再少 10%(DEFAULT_SCALE = 0.1)
  • 逐层下移:每层按卡片高度的 1/14 向下偏移(DEFAULT_TRANSLATE_Y = 14)
  • 手势接管:最前卡片注册触摸监听,手指按下时调用 ItemTouchHelper.startSwipe() 交给滑动手势

同屏数量由 CardConfig.java 的 DEFAULT_SHOW_ITEM = 3 控制。

2️⃣ CardItemTouchHelperCallback:让卡片"滑"得动

CardItemTouchHelperCallback.java 继承 ItemTouchHelper.Callback,只开放左右滑动手势。灵魂在于 onChildDraw 重写(#L83-L124):

  1. 用横向位移 dX 计算滑动进度 ratio(限制在 -1 ~ 1)
  2. setRotation(ratio × 15°) 让卡片实时倾斜,滑得越远角度越大
  3. 同步调整后方卡片的缩放与 Y 偏移,实现"下一张卡顶出"效果

卡片完全滑出后,onSwiped(#L60-L75)移除数据、刷新适配器并回调滑出方向。

3️⃣ OnSwipeListener:3 个回调定制交互

OnSwipeListener.java 定义了三个钩子:

  • onSwiping — 滑动中实时回调,用 ratio 做淡入/淡出动画(示例里的点赞/无感图标就是靠它渐显)
  • onSwiped — 卡片完全滑出,可拿到对应数据并重置动画
  • onSwipedClear — 全部卡片滑完,方便触发加载更多

⚡ 快速接入:3 步集成指南

第 1 步:在 build.gradle 中添加依赖

compile 'me.yuqirong:cardswipelayout:1.0.0'

第 2 步:像平时一样初始化 RecyclerView 并设置 Adapter。

第 3 步:4 行代码接入卡片滑动

CardItemTouchHelperCallback callback = new CardItemTouchHelperCallback(adapter, dataList);
ItemTouchHelper touchHelper = new ItemTouchHelper(callback);
recyclerView.setLayoutManager(new CardLayoutManager(recyclerView, touchHelper));
touchHelper.attachToRecyclerView(recyclerView);

再给 callback 注册 OnSwipeListener,仿探探卡片滑动效果即告完成。完整可运行示例见 MainActivity.java。

🎨 示例拆解:还原一套完整交互

示例模块 app/ 以头像数据模拟交友 App 的卡片浏览闭环:

  • 卡片布局 item.xml:上方头像 + 下方姓名/年龄/星座,圆角由自定义 RoundImageView.java 实现
  • 滑动中:卡片微微变透明,"喜欢/无感"图标按方向各自渐显
  • 滑出后:重置视图并用 Toast 提示滑出方向
  • 全部滑完:延迟 3 秒重新加载数据,模拟下拉刷新

✅ 适用场景与注意事项

适合这些场景

  • 交友、社交类 App 的推荐页
  • 卡片式内容浏览、答题翻卡等列表交互

需要注意

  • 库基于旧版 android.support.v7 支持库,新项目需自行迁移 androidx(工作量小,多为包名替换)
  • 示例使用 notifyDataSetChanged 刷新,大数据量建议优化为差量更新
  • 缩放、偏移、倾斜等视觉参数集中在 CardConfig.java,改几个数字即可调整风格

📚 核心文件清单

文件 职责
CardLayoutManager.java 自定义布局:卡片叠放与居中
CardItemTouchHelperCallback.java 滑动手势、倾斜与联动动画、数据移除
CardConfig.java 可调参数常量
OnSwipeListener.java 回调接口
MainActivity.java 完整可运行 Demo

获取源码:

git clone https://gitcode.com/gh_mirrors/ca/CardSwipeLayout
登录后查看全文
CardSwipeLayout