CardSwipeLayout项目全览:用3个核心类实现仿探探卡片滑动布局的开源利器
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):
- 用横向位移 dX 计算滑动进度 ratio(限制在 -1 ~ 1)
setRotation(ratio × 15°)让卡片实时倾斜,滑得越远角度越大- 同步调整后方卡片的缩放与 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