c790cee472
All checks were successful
continuous-integration/drone/push Build is passing
- Created comprehensive Android app requirements document - Built complete Android project with Kotlin and Jetpack Compose - Implemented task management with control and display screens - Added Android widget with 5-minute auto-refresh capability - Integrated Room database for offline support - Set up MVVM architecture with Hilt dependency injection - Configured Retrofit for API communication - Added Material Design 3 theming and UI components
124 lines
3.0 KiB
Markdown
124 lines
3.0 KiB
Markdown
# Calendar Widget Android App
|
||
|
||
基于 Calendar Widget 系统的原生 Android 应用实现。
|
||
|
||
## 功能特性
|
||
|
||
- 📱 **原生 Android 体验**：使用 Kotlin 和 Jetpack Compose 构建
|
||
- 📋 **任务管理**：完整的任务增删改查功能
|
||
- 🎨 **Material Design 3**：现代化的 UI 设计
|
||
- 📊 **双视图模式**：控制页面和展示页面
|
||
- 🔄 **实时同步**：与服务器 API 实时同步
|
||
- 💾 **离线支持**：本地数据库缓存
|
||
- ⚡ **桌面小组件**：支持多种尺寸，5分钟自动刷新
|
||
|
||
## 技术架构
|
||
|
||
- **语言**：Kotlin
|
||
- **UI**：Jetpack Compose
|
||
- **架构**：MVVM + Repository Pattern
|
||
- **依赖注入**：Hilt
|
||
- **网络**：Retrofit + OkHttp
|
||
- **数据库**：Room
|
||
- **协程**：Kotlin Coroutines + Flow
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
android-app/
|
||
├── app/
|
||
│ ├── src/main/java/com/tunpok/calendarwidget/
|
||
│ │ ├── data/ # 数据层
|
||
│ │ │ ├── api/ # API 接口定义
|
||
│ │ │ ├── database/ # Room 数据库
|
||
│ │ │ ├── model/ # 数据模型
|
||
│ │ │ └── repository/ # 数据仓库
|
||
│ │ ├── di/ # Hilt 依赖注入
|
||
│ │ ├── ui/ # UI 层
|
||
│ │ │ ├── control/ # 控制页面
|
||
│ │ │ ├── display/ # 展示页面
|
||
│ │ │ ├── widget/ # 桌面小组件
|
||
│ │ │ ├── components/ # 共享组件
|
||
│ │ │ └── theme/ # 主题配置
|
||
│ │ └── utils/ # 工具类
|
||
│ └── src/main/res/ # 资源文件
|
||
├── gradle/ # Gradle 配置
|
||
└── build.gradle.kts # 构建脚本
|
||
```
|
||
|
||
## 构建与运行
|
||
|
||
### 前置要求
|
||
|
||
- Android Studio Arctic Fox 或更高版本
|
||
- JDK 17
|
||
- Android SDK 34
|
||
- Kotlin 1.9.20+
|
||
|
||
### 构建步骤
|
||
|
||
1. 克隆项目：
|
||
```bash
|
||
cd android-app
|
||
```
|
||
|
||
2. 打开 Android Studio，导入项目
|
||
|
||
3. 配置 API 设置（首次运行时在应用内配置）：
|
||
- API Key: 你的 API 密钥
|
||
- API Host: 服务器地址
|
||
|
||
4. 构建并运行：
|
||
- 点击 Run 按钮或使用快捷键 Shift+F10
|
||
|
||
### 生成 APK
|
||
|
||
```bash
|
||
./gradlew assembleRelease
|
||
```
|
||
|
||
生成的 APK 位于：`app/build/outputs/apk/release/`
|
||
|
||
## 小组件配置
|
||
|
||
1. 长按桌面空白处
|
||
2. 选择"小组件"
|
||
3. 找到"Calendar Widget"
|
||
4. 选择合适的尺寸：
|
||
- 小型 (2x1)：显示1个任务
|
||
- 中型 (2x2)：显示4个任务
|
||
- 大型 (4x2)：显示8个任务
|
||
5. 拖动到桌面
|
||
|
||
小组件会每5分钟自动刷新，也可以点击刷新按钮手动更新。
|
||
|
||
## 开发说明
|
||
|
||
### 添加新功能
|
||
|
||
1. 在对应的包中创建新文件
|
||
2. 使用 Hilt 注解进行依赖注入
|
||
3. 遵循 MVVM 架构模式
|
||
4. 使用 Compose 构建 UI
|
||
|
||
### 调试
|
||
|
||
- 启用 OkHttp 日志：已在 `AppModule` 中配置
|
||
- 查看数据库：使用 Android Studio 的 Database Inspector
|
||
- 网络调试：使用 Charles 或 Flipper
|
||
|
||
## 测试
|
||
|
||
运行单元测试：
|
||
```bash
|
||
./gradlew test
|
||
```
|
||
|
||
运行 UI 测试：
|
||
```bash
|
||
./gradlew connectedAndroidTest
|
||
```
|
||
|
||
## License
|
||
|
||
MIT |