calendar-widget/android-app

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. 克隆项目：

cd android-app

2. 打开 Android Studio，导入项目

3. 配置 API 设置（首次运行时在应用内配置）：

   • API Key: 你的 API 密钥
   • API Host: 服务器地址

4. 构建并运行：

   • 点击 Run 按钮或使用快捷键 Shift+F10

生成 APK

./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

测试

运行单元测试：

./gradlew test

运行 UI 测试：

./gradlew connectedAndroidTest

License

MIT