DrinkTracker 是一款使用 SwiftUI + SwiftData 构建的原生 iOS 饮水记录应用。它不仅仅是一个简单的记录工具，更是一个完整的饮水健康管理平台，集成了智能提醒、数据可视化、成就激励、Apple Health 同步等功能。
- 🎯 极简记录 — 一键记录，3秒撤销，零学习成本
- 📊 深度统计 — 趋势图、日历视图、时段分析，全面掌握饮水习惯
- 🏆 成就激励 — 勋章系统 + 连续打卡，让喝水变得有趣
- 🔔 智能提醒 — 基于历史数据分析，在您最需要的时候提醒
- 🏥 健康集成 — 无缝对接 Apple Health，数据互通
- 🔒 隐私优先 — 所有数据存储在设备本地，绝不上传服务器
| 功能 | 描述 |
|---|---|
| ⚡ 一键记录 | 主屏幕焦点按钮，点击即记录默认容量 |
| 🎯 进度环 | 精美圆环进度条 + 水波动画，直观显示今日进度 |
| 🧃 饮品分类 | 9种预置饮品（白水、茶水、咖啡、牛奶、果汁、碳酸饮料、奶茶、功能饮料、其他） |
| 🏔️ 饮水金字塔 | 6级健康等级颜色标识，引导健康饮品选择 |
| ⏱️ 快捷容量 | 100ml-500ml 预设大按钮，支持记住最常用3个容量 |
| 🥤 自定义水杯 | 录入个人水杯（办公杯500ml、家用杯300ml等），点击即记录 |
| ✏️ 编辑与删除 | 点击记录可编辑饮品类型和饮水量，左滑或长按可删除 |
| ↩️ 3秒撤销 | 记录后3秒内可撤回，误触无忧 |
| 🌊 水波动画 | 进度环内嵌水波荡漾 + 气泡上升微动画 |
| 功能 | 描述 |
|---|---|
| 📈 趋势图表 | 近7天/30天饮水量柱状图（Swift Charts），带目标线 |
| 🥧 饮品分布 | 环形饼图展示各饮品占比 |
| 📅 日历视图 | 按月展示每天完成情况：🟢达标 🟡50%+ 🔴不足 |
| ⏰ 时段分析 | 6:00-23:00 每小时饮水量柱状图 |
| 📋 周报/月报 | 详细报告生成，含规律分析 + 健康建议，支持分享 |
| 🏆 成就系统 | 6种勋章（一周达人、补水王者、百杯勇士、千杯不醉等） |
| 🔥 连续打卡 | 实时显示连续达标天数 |
| 功能 | 描述 |
|---|---|
| ⏱️ 间隔模式 | 每隔 1/2/3/4 小时提醒一次 |
| 🕐 自定义时间点 | 用户设定多个精确提醒时间 |
| 🌙 免打扰 | 夜间免打扰时段（默认 22:00-7:00） |
| 📆 工作日/周末 | 支持分别设置差异化提醒 |
| 💬 自定义消息 | 提醒文字可自定义，预设4种快捷文案 |
| 🧠 智能提醒 | 分析历史数据，在低饮水时段额外提醒 |
| 功能 | 描述 |
|---|---|
| 🎯 智能目标 | 根据体重自动计算（体重×30ml），支持手动调整（500-5000ml） |
| 🏃 场景调整 | 运动日 +500ml、炎热天气 +300ml |
| ❤️ Apple Health | 读取体重/性别/运动数据，写入饮水量/咖啡因 |
| ☁️ iCloud 同步 | 多设备数据同步（iPhone ↔ iPad） |
| 📤 数据导出 | CSV 格式导出饮水记录 |
| 💾 备份恢复 | iCloud 备份与恢复 |
| 类型 | 描述 |
|---|---|
| 小尺寸 | 显示今日进度百分比圆环 |
| 中尺寸 | 进度条 + 饮水量 + 快捷记录按钮 |
| 锁屏圆形 | Gauge 进度指示器 |
| 锁屏矩形 | 饮水量 + 进度条 + 百分比 |
- 🌊 水波荡漾 — 进度环内的水波流动效果
- 🫧 气泡上升 — 水中气泡随机浮动
- 🎊 目标庆祝 — 达成目标时撒花庆祝动画
- 💧 记录反馈 — 水滴弹跳微动画
- 🏆 成就解锁 — 勋章弹出 + 星光特效
| 技术 | 版本 | 用途 |
|---|---|---|
| Swift | 5.9 | 主要编程语言 |
| SwiftUI | iOS 17+ | 声明式 UI 框架 |
| SwiftData | iOS 17+ | 数据持久化（替代 CoreData） |
| Swift Charts | iOS 16+ | 数据可视化图表 |
| HealthKit | — | Apple Health 数据读写 |
| WidgetKit | iOS 16+ | 主屏幕/锁屏小组件 |
| UserNotifications | — | 本地通知管理 |
┌─────────────────────────────────────────────┐
│ Views │
│ (SwiftUI Views + ViewModels) │
├─────────────────────────────────────────────┤
│ Helpers │
│ (DataHelper - 数据计算逻辑) │
├─────────────────────────────────────────────┤
│ Services │
│ (HealthKit / Notifications / iCloud) │
├─────────────────────────────────────────────┤
│ Models │
│ (SwiftData @Model 数据模型) │
├─────────────────────────────────────────────┤
│ Storage │
│ (SwiftData Container / UserDefaults) │
└─────────────────────────────────────────────┘
- 声明式 UI — 全面使用 SwiftUI，代码即界面
- 响应式数据 — SwiftData @Query 自动更新 UI
- 模块化设计 — Views/Models/Services/Helpers 清晰分层
- 单例服务 — HealthKitManager、NotificationManager 统一管理
- 本地优先 — 所有数据设备本地存储，可选云同步
Drinking/
├── 📄 DrinkingApp.swift # App 入口 + AppState
├── 📄 ContentView.swift # TabView 主界面 + UndoToast
├── 📄 Drinking.entitlements # HealthKit 权限声明
│
├── 📂 Models/
│ ├── 📄 DrinkType.swift # 饮品类型枚举 + 健康等级 + 子类型
│ └── 📄 DataModels.swift # SwiftData 模型（5个 @Model）
│ ├── DrinkRecord # 饮水记录
│ ├── UserProfile # 用户档案
│ ├── CustomCup # 自定义水杯
│ ├── Achievement # 成就
│ └── DailyGoal # 每日目标
│
├── 📂 Views/
│ ├── 📂 Home/
│ │ ├── 📄 HomeView.swift # 首页主视图
│ │ ├── 📄 EditRecordView.swift # 编辑记录视图
│ │ ├── 📄 WaterWaveView.swift # 水波动画组件
│ │ ├── 📄 DrinkTypeSelectorView.swift # 饮品选择器 Sheet
│ │ └── 📄 CustomInputView.swift # 自定义输入 + 添加水杯
│ │
│ ├── 📂 Statistics/
│ │ ├── 📄 StatisticsView.swift # 统计主视图（图表+日历）
│ │ └── 📄 ReportView.swift # 周报/月报视图
│ │
│ ├── 📂 Reminders/
│ │ └── 📄 ReminderSettingsView.swift # 提醒设置视图
│ │
│ ├── 📂 Profile/
│ │ └── 📄 ProfileView.swift # 个人中心 + 设置 + 隐私政策
│ │
│ └── 📂 Components/
│ └── 📄 CelebrationView.swift # 庆祝/成就动画组件
│
├── 📂 Helpers/
│ └── 📄 DataHelper.swift # 数据计算工具类
│
├── 📂 Services/
│ ├── 📄 HealthKitManager.swift # HealthKit 集成服务
│ └── 📄 NotificationManager.swift # 通知管理服务
│
└── 📂 Assets.xcassets/ # 资源文件
├── AppIcon.appiconset/ # 应用图标
└── AccentColor.colorset/
DrinkingWidget/
└── 📄 DrinkingWidget.swift # WidgetKit 小组件
├── DrinkingSmallWidget # 小尺寸
├── DrinkingMediumWidget # 中尺寸
├── DrinkingLockScreenWidget # 锁屏圆形
└── DrinkingLockScreenRectangularWidget # 锁屏矩形
| 要求 | 版本 |
|---|---|
| macOS | 13.0+ (Ventura) |
| Xcode | 15.0+ |
| iOS Deployment Target | 17.0+ |
| Swift | 5.9+ |
- 克隆仓库
git clone https://github.com/Pikulo/DrinkTracker.git
cd DrinkTracker- 打开项目
open Drinking.xcodeproj- 配置签名
在 Xcode 中选择项目 Drinking → Signing & Capabilities：
- 选择你的 Team（个人开发者账号即可）
- Bundle Identifier 可保持默认或修改
- 选择目标设备
- 模拟器：选择任意 iPhone 模拟器（HealthKit 功能不可用）
- 真机：选择已连接的 iPhone（完整功能体验）
- 运行项目
按 ⌘ + R 或点击
📌 请在真机或模拟器上运行后截图，替换以下占位图
| 首页 | 统计 | 提醒 | 个人中心 |
|---|---|---|---|
 |
 |
 |
 |
| 饮品选择 | 日历视图 | 成就系统 | 编辑记录 |
|---|---|---|---|
 |
 |
 |
 |
- 饮水记录（9种饮品 + 健康等级）
- 一键记录 + 3秒撤销
- 记录编辑与删除
- 自定义水杯管理
- 数据统计（趋势图、饼图、日历、时段分布）
- 周报/月报生成与分享
- 成就勋章系统
- 智能饮水提醒
- Apple Health 集成
- 主屏幕/锁屏小组件
- 水波动画 + 庆祝特效
- Apple Watch 端快速记录
- Siri 快捷指令集成
- 体重记录与关联分析
- 运动后自动补水提醒（基于 HealthKit 运动数据）
- 水滴宠物/植物养成系统
- 深色模式优化
- 多语言支持（English / 日本語）
- 多人/家庭模式
- 饮水拍照记录
- 社区打卡分享
- PDF 格式导出报告
- iPad 专属布局优化
- macOS Catalyst 支持
- 在
Drinking/Models/DrinkType.swift的DrinkType枚举中添加新 case：
case herbalTea = "花草茶"-
为新类型补充 icon、healthLevel、color 属性
-
如需子类型，参照
TeaSubtype创建新枚举
- 在
AchievementType枚举中添加新 case：
case nightOwl = "夜猫子"-
补充 icon、color、description、requirement 属性
-
在成就检查逻辑中添加解锁条件
欢迎贡献代码、报告问题或提出建议！
- Fork 本仓库
- 创建你的特性分支：
git checkout -b feature/amazing-feature - 提交你的更改：
git commit -m 'Add amazing feature' - 推送到分支：
git push origin feature/amazing-feature - 打开一个 Pull Request
Q: 为什么使用 SwiftData 而不是 CoreData？
SwiftData 是 Apple 在 WWDC23 推出的新一代数据持久化框架，与 SwiftUI 深度集成，语法更简洁，是 CoreData 的现代化替代。本项目要求 iOS 17.0+。
Q: HealthKit 在模拟器上不可用怎么办？
HealthKit 需要在真机上测试。模拟器上 App 会正常运行，只是 Health 相关功能（读取体重、写入饮水量等）不可用。
Q: 如何修改默认饮水目标？
进入「个人中心」→ 点击顶部个人信息区域 → 修改「每日饮水目标」。也可以开启「自定义目标」关闭自动推荐。
Q: 数据存储在哪里？会丢失吗？
所有数据使用 SwiftData 存储在设备本地的 SQLite 数据库中。卸载 App 会清除数据。建议开启 iCloud 同步功能以提供备份。
本项目基于 MIT License 开源。
- Apple Developer Documentation — 官方技术文档
- SwiftUI by Example — SwiftUI 学习资源
- SF Symbols — Apple 官方图标库
如果觉得这个项目有帮助，请给一个 ⭐ Star 支持一下！
Made with ❤️ and SwiftUI