From 98e91c273edc8a4c0b175c6278a3b4fce3589953 Mon Sep 17 00:00:00 2001 From: xfy Date: Thu, 14 May 2026 18:01:03 +0800 Subject: [PATCH] Rewrite README as project overview and add development guide Replace the default KMP template README with a concise project description in Chinese, and add DEVELOPMENT.md with setup, build, test, and convention instructions. Co-Authored-By: Claude Opus 4.7 --- DEVELOPMENT.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 41 ++++++------------ 2 files changed, 126 insertions(+), 28 deletions(-) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..6786acf --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,113 @@ +# 开发指南 + +## 环境要求 + +- JDK 17+ +- Android Studio (Ladybug 或更新版本) +- Xcode 16+ (仅 iOS 构建需要) +- Kotlin Multiplatform 插件 (Android Studio 内置) + +## 项目结构 + +``` +YaYa/ +├── shared/ # 共享模块 — 所有 UI 和业务逻辑 +│ ├── src/commonMain/kotlin/ # 跨平台代码 +│ │ └── plus/rua/project/ +│ │ ├── App.kt # 应用入口 +│ │ ├── CalendarViewModel.kt # 日历状态管理 +│ │ └── ui/ +│ │ ├── CalendarMonthView.kt # 顶层日历屏幕 +│ │ ├── CalendarMonthPage.kt # 单月网格页 +│ │ ├── CalendarPager.kt # 月视图无限分页 +│ │ ├── WeekPager.kt # 周视图无限分页 +│ │ ├── DayCell.kt # 单日圆圈组件 +│ │ ├── MonthHeader.kt # 年月标题 + 周数 +│ │ ├── WeekdayHeader.kt # 星期标题行 +│ │ └── BottomCard.kt # 底部拖拽卡片 +│ ├── src/commonTest/kotlin/ # 共享测试 +│ ├── src/androidMain/kotlin/ # Android 预览工具 +│ └── src/iosMain/kotlin/ # iOS ViewController 工厂 +├── androidApp/ # Android 薄壳 — MainActivity → App() +├── iosApp/ # iOS 入口 — Xcode 项目 +└── gradle/libs.versions.toml # 版本目录 — 统一管理依赖版本 +``` + +## 运行 + +### Android + +```bash +# 命令行构建 +./gradlew :androidApp:assembleDebug + +# 安装到设备 +./gradlew :androidApp:installDebug +``` + +或在 Android Studio 中选择 `androidApp` 配置直接运行。 + +### iOS + +1. 先执行一次 Gradle 同步：`./gradlew :shared:generateDummyFramework` +2. 在 Xcode 中打开 `iosApp/iosApp.xcworkspace` +3. 选择目标设备或模拟器，点击 Run + +> 首次打开可能需要等待 Xcode 索引完成。如果报 framework 错误，重新执行 Gradle 同步即可。 + +## 测试 + +```bash +# 运行所有共享模块测试 +./gradlew :shared:allTests + +# 运行单个测试类 (Android host) +./gradlew :shared:androidHostTest --tests "plus.rua.project.ComposeAppCommonTest" +``` + +## 开发约定 + +### 代码组织 + +- 所有 Compose UI 和 ViewModel 代码放在 `shared/commonMain`，不按平台拆分 +- 平台特定代码仅放在对应的 `androidMain` / `iosMain` +- UI 组件统一在 `plus.rua.project.ui` 包下 + +### Compose 规范 + +- `Modifier` 参数始终放在最后 +- 回调参数使用 `on` 前缀：`onDateClick`、`onMonthChanged` +- 公开 `@Composable` 函数需要 KDoc 注释（详见 `COMMENTS.md`） + +### 日期处理 + +- 统一使用 `kotlinx-datetime`，禁止使用 `java.util.Calendar` +- 周起始为周一 (ISO 8601) +- `monthNumber` 访问需要 `@Suppress("DEPRECATION")` 并附行内注释说明原因 + +### UI 文案 + +- 界面文字为中文（星期标题 "一二三四五六日"，月份格式 "2026年5月"） + +### 依赖管理 + +- 所有版本声明在 `gradle/libs.versions.toml`，不硬编码 +- 新增依赖先在版本目录添加条目，再在 `build.gradle.kts` 中引用 + +## 架构概览 + +``` +CalendarMonthView (顶层屏幕) + ├── MonthHeader 年月标签 + ISO 周数 + ├── WeekdayHeader 固定星期行 + ├── CalendarPager 月视图无限分页 (Int.MAX_VALUE 页) + │ └── CalendarMonthPage 6×7 DayCell 网格，折叠时压缩非选中行 + │ └── DayCell 单日圆圈，选中/今日状态 + ├── WeekPager 周视图无限分页 (折叠态) + │ └── DayCell + └── BottomCard 拖拽手柄，驱动折叠/展开手势 +``` + +**折叠动画：** `CalendarViewModel.collapseProgress` 控制 0f(月)↔1f(周) 过渡。`BottomCard` 捕获垂直拖拽，释放时超过 50% 则弹簧动画吸附到最近状态。完全折叠后 `WeekPager` 替代 `CalendarPager` 实现高效单周分页。 + +**分页映射：** 两个 Pager 均使用 `Int.MAX_VALUE` 页数，中心页为 `Int.MAX_VALUE / 2`。页码到日期为算术转换，无索引列表。两者均跳过初始 `snapshotFlow` 发射 (`.drop(1)`) 以保留首次渲染时的"今日"选中。 diff --git a/README.md b/README.md index 7e7d049..1adebe9 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,20 @@ -This is a Kotlin Multiplatform project targeting Android, iOS. +# YaYa -* [/composeApp](./composeApp/src) is for code that will be shared across your Compose Multiplatform applications. - It contains several subfolders: - - [commonMain](./composeApp/src/commonMain/kotlin) is for code that’s common for all targets. - - Other folders are for Kotlin code that will be compiled for only the platform indicated in the folder name. - For example, if you want to use Apple’s CoreCrypto for the iOS part of your Kotlin app, - the [iosMain](./composeApp/src/iosMain/kotlin) folder would be the right place for such calls. - Similarly, if you want to edit the Desktop (JVM) specific part, the [jvmMain](./composeApp/src/jvmMain/kotlin) - folder is the appropriate location. +基于 Kotlin Multiplatform 与 Compose Multiplatform 的日历应用，Android 和 iOS 共享 UI。 -* [/iosApp](./iosApp/iosApp) contains iOS applications. Even if you’re sharing your UI with Compose Multiplatform, - you need this entry point for your iOS app. This is also where you should add SwiftUI code for your project. +月视图与周视图之间支持流畅的折叠/展开过渡——拖拽切换，弹簧动画自动吸附。无限分页，ISO 8601 周起始，Material 3。 -### Build and Run Android Application +## 构建 -To build and run the development version of the Android app, use the run configuration from the run widget -in your IDE’s toolbar or build it directly from the terminal: -- on macOS/Linux - ```shell - ./gradlew :composeApp:assembleDebug - ``` -- on Windows - ```shell - .\gradlew.bat :composeApp:assembleDebug - ``` +```bash +# Android +./gradlew :androidApp:assembleDebug -### Build and Run iOS Application +# iOS — 在 Xcode 中打开 iosApp/ 运行 +``` -To build and run the development version of the iOS app, use the run configuration from the run widget -in your IDE’s toolbar or open the [/iosApp](./iosApp) directory in Xcode and run it from there. +## 技术栈 ---- - -Learn more about [Kotlin Multiplatform](https://www.jetbrains.com/help/kotlin-multiplatform-dev/get-started.html)… \ No newline at end of file +- Kotlin 2.3 · Compose Multiplatform 1.10 · Material 3 +- `kotlinx-datetime` 处理所有日期逻辑 +- 双模块：`:shared`（UI + 逻辑）· `:androidApp`（薄壳）