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 <noreply@anthropic.com>
This commit is contained in:
parent
bacc2bc8dc
commit
98e91c273e
113
DEVELOPMENT.md
Normal file
113
DEVELOPMENT.md
Normal file
@ -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)`) 以保留首次渲染时的"今日"选中。
|
||||
41
README.md
41
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)…
|
||||
- Kotlin 2.3 · Compose Multiplatform 1.10 · Material 3
|
||||
- `kotlinx-datetime` 处理所有日期逻辑
|
||||
- 双模块：`:shared`（UI + 逻辑）· `:androidApp`（薄壳）
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user