Card Stack Android

一个使用 Kotlin 与 Jetpack Compose 编写的原生 Android 扇形卡片栈组件，不包含 WebView。

Important

本项目是 leset0ng/card-stack 的独立 Android 原生移植版，并非上游官方 Android 版本。原项目与本项目均依照 MIT License 分发，详细来源见 NOTICE 和 UPSTREAM.md。

查看 Material 3 实时调参面板

特性

• 上滑切换下一张、下滑返回上一张，横向位移会自然跟手
• 位移与松手速度共同决定是否翻页，未达到阈值时弹簧回弹
• 前后卡片联动、扇形常驻、渐进模糊与右侧进度圆点
• 对返回上一张时的卡片提升和退场路径做了原生侧平滑处理
• 短距离松手会自动匹配最大拖拽距离的阻尼节奏
• 支持受控/非受控索引，以及父级驱动的连续滚动
• Demo 使用 Material 3、系统动态色与深浅色主题，实时调参采用 Modal Bottom Sheet
• 调参面板可直接调节卡片数量、尺寸、姿态、手势和动画

环境要求

• Android Studio 或 JDK 17
• Android SDK 36
• 最低 Android 版本：API 24
• 模糊效果需要 Android 12（API 31）或更高版本；低版本保留位移与旋转动画

工程结构

• cardstack：可复用的 Jetpack Compose 组件库
• app：组件演示与实时调参应用
• docs/media：README 使用的真机截图与演示视频

快速开始

当前版本尚未发布到 Maven 仓库。可以先把 cardstack 模块放进自己的工程，或直接克隆本仓库并添加模块依赖：

dependencies {
    implementation(project(":cardstack"))
}

创建卡片并使用受控索引：

var index by remember { mutableIntStateOf(0) }

val cards = cardStackItems(items, key = Item::id) { item ->
    MyCard(item)
}

CardStack(
    cards = cards,
    index = index,
    animateIndexChanges = true,
    indexDirection = CardStackIndexDirection.Auto,
    onIndexChange = { index = it },
    width = 320.dp,
    height = 320.dp,
    motion = CardStackMotionConfig(
        flipDistanceRatio = 0.18f,
        releaseSpringStiffness = 260f,
        deckSpringStiffness = 300f,
        springDampingRatio = 0.84f,
        shortReleaseCadenceScale = 0.62f,
    ),
)

不传 index 时，组件使用内部状态；可以通过 defaultIndex 指定初始卡片。后层卡片默认使用 2.dp 和 4.dp 的渐进模糊，也可以通过 second、third 传入自定义 CardPose。

构建与验证

Windows：

.\gradlew.bat :cardstack:testDebugUnitTest :cardstack:assembleRelease :app:assembleDebug

macOS / Linux：

./gradlew :cardstack:testDebugUnitTest :cardstack:assembleRelease :app:assembleDebug

输出位置：

• Demo APK：app/build/outputs/apk/debug/app-debug.apk
• Library AAR：cardstack/build/outputs/aar/cardstack-release.aar

发布说明

仓库只提交源码、Gradle Wrapper 和演示媒体。APK/AAR 不进入 Git 历史，应放到 GitHub Releases 中。首次发布建议使用 v0.1.0 标签，并在 Release 正文中再次注明上游来源。

公开的 Kotlin package 与 Android namespace 已统一为 io.github.defatestar.cardstack，Demo applicationId 为 io.github.defatestar.cardstack.demo。预留 Maven groupId 为 io.github.defatestar，但目前尚未发布可用的 Maven 依赖坐标。

许可证与署名

本项目保留了上游完整的 MIT 许可证和版权声明。修改版可以继续使用 MIT，但不得删除上游的版权与许可文本。详见 LICENSE、NOTICE 和 UPSTREAM.md。