「静」基于 Flutter 构建,以柔和的暖陶色系、优雅的衬线排版与克制的留白,为用户提供引导冥想、4·7·8 呼吸练习、睡眠故事与自然音景等静心内容。应用遵循 本地优先 的设计理念——练习历史、收藏、续听进度等个人数据全部保存在设备本地,无账号体系、不收集任何用户数据。
- 引导冥想 — 按「放松 / 专注 / 睡眠 / 减压」分类的冥想课程,支持搜索、筛选与收藏
- 沉浸式播放器 — 暗色播放界面与脉动光球动画;在线音频播放(
just_audio),无音频源时自动降级为计时模式 - 完整播放控制 — 进度拖动、±10 秒快进快退、音量调节、15/30/45/60 分钟定时关闭
- 续听进度 — 中途退出自动记录位置,首页「继续聆听」一键从上次位置恢复
- 迷你播放条 — 收起播放器后全局悬浮,不打断浏览
- 4·7·8 呼吸法 — 吸气 4 秒、屏息 7 秒、呼气 8 秒的完整引导会话
- 可配置轮数 — 4 / 8 / 12 轮三档时长,适配不同场景
- 相位同步动画 — 圆圈的扩张、保持与收缩与呼吸节奏逐秒对齐,辅以会话进度环与相位触感反馈
- 睡眠故事 与 环境音景(雨声 / 海浪 / 篝火 / 白噪),陪伴入睡
- 配合定时关闭,播完自动停止
- 练习统计 — 连续天数、累计时长、本周分钟数图表,由真实练习记录驱动
- 最近练习 — 按时间排列的练习历史
- 成就系统 — 六枚由真实数据解锁的徽章(第一步、七日坚持、早起鸟、呼吸行者、安眠者、静心者)
- 个性化 — 修改昵称、按时段变化的问候语、一键清除本地数据
- 深色模式 — 跟随系统 / 浅色 / 深色三档外观设置,暖棕暗色主题全页面适配
- 全局按压缩放反馈与触感振动、页面切换淡入过渡、列表交错入场动画
- 播放器自底部滑入滑出、底部导航选中动效
- 响应式布局,手机 / 平板 / 桌面 / Web 自适应
- 使用系统默认字体,无字体资源体积负担
每次 main 分支更新,CI 会自动构建内置 Mock 数据的 Android 测试包:
- 用手机浏览器打开 mock-latest Release
- 下载
jing-mock-release.apk - 允许「安装未知来源应用」后安装
注意:测试包使用 debug 签名,仅供内部测试,请勿分发;演示音频为在线资源,播放需要联网。
| 依赖 | 版本 |
|---|---|
| Flutter SDK | ≥ 3.10 |
| Dart | ≥ 3.10 |
| JDK(Android 构建) | 17 |
# 克隆仓库
git clone https://github.com/Chenfyuan/meditation.git
cd meditation
# 安装依赖
flutter pub get
# 运行(连接设备或模拟器)
flutter run
# 指定平台运行
flutter run -d chrome # Webflutter build apk --release # Android APK
flutter build web --release # Web(产物在 build/web/)
flutter build ios --release # iOS(需 macOS 与签名证书)应用通过仓储层抽象内容来源,默认使用内置 Mock 数据,可通过编译期变量切换到远程 API:
# 默认:内置 Mock 数据(无需后端)
flutter run
# 连接远程内容 API(backend/ 目录提供 NestJS 参考实现)
flutter run \
--dart-define=USE_REMOTE_CONTENT=true \
--dart-define=CONTENT_API_BASE_URL=https://your-api.example.com后端参考实现位于 backend/(NestJS + Prisma),详见其目录内文档。
UI(Screens / Widgets)
│ Provider(context.watch / read)
▼
状态层(ChangeNotifier Providers)
│ 依赖注入(构造函数)
▼
仓储层(Repositories:内容 / 历史 / 收藏 / 续听 / 设置)
│
├── MockContentRepository(内置数据)
├── RemoteContentRepository(HTTP API)
└── SharedPreferences 持久化(本地个人数据)
lib/
├── main.dart # 入口与依赖装配
├── app.dart # 应用外壳:导航、播放器覆盖层、响应式布局
├── theme/ # 色彩、字体、ThemeData
├── models/ # 数据模型(冥想、睡眠内容、练习记录、成就、续听会话)
├── providers/ # 状态管理(Player / Breathing / Home / Explore / Sleep / Profile / Settings)
├── repositories/ # 仓储层(内容、练习历史、收藏、续听进度)
├── services/ # API 客户端与异常
├── screens/ # 六个核心页面
└── widgets/ # 复用组件(呼吸圆圈、播放光球、动效组件等)
- 播放器为全局覆盖层 — 由
PlayerProvider驱动,任意页面均可唤起,收起后显示迷你播放条 IndexedStack保持页面状态 — 切换 Tab 不丢失滚动位置与输入,外层叠加淡入过渡- 仓储接口 + 双实现 — Mock 与 Remote 数据源可无缝切换,便于离线开发与真实部署
- 练习记录本地化 — 完成 80% 以上即计入历史;呼吸会话、睡眠定时同样入账
- 音频降级策略 — 音频加载失败自动切换计时模式,弱网环境功能不中断
flutter analyze # 静态分析(零告警)
flutter test # 单元测试 + 组件测试(19 个用例)测试覆盖:呼吸会话相位时序(fake_async)、练习历史汇总与连续天数、收藏筛选、续听会话序列化、时段问候,以及首页 / 呼吸 / 探索 / 我的四个页面的组件测试。
CI(GitHub Actions)在每次推送到 main 时执行 analyze → test → build,全部通过后才发布测试包。
图标与启动屏源图位于 assets/icon/,由脚本程序化生成(暖铜渐变 + 衬线「静」字 + 圆相细环)。更换后执行:
dart run flutter_launcher_icons # 重新生成全平台应用图标
dart run flutter_native_splash:create # 重新生成原生启动屏| 色彩 | 色值 | 用途 |
|---|---|---|
| 暖铜 | #B8865F |
主色调 |
| 亮铜 | #E0BD97 |
渐变亮部 |
| 奶油 | #EFE8DE |
页面背景 |
| 深棕 | #3A3127 |
文字 / 深色元素 |
| 鼠尾草 | #94A07A |
辅助绿 |
| 玫瑰陶 | #D8AA98 |
辅助粉 |
所有个人数据(练习历史、收藏、续听进度、昵称)仅保存在设备本地(shared_preferences),应用不含账号体系,不收集、不上传任何用户数据。
- 正式签名与应用商店上架(Google Play / App Store)
- 接入生产内容 API 与真实音频版权内容
- 每日练习提醒(本地通知)
- 后台播放与锁屏媒体控制
- 多语言支持(英文)
© 2026 Chenfyuan。保留所有权利。
本仓库当前未附带开源许可证,如需使用请先与作者联系。