3.0 KiB
3.0 KiB
iOS Widget（高层规范）
1. 背景与目标
当前客户端仅在设置页展示了“小组件说明文案”，并未实现真正的 iOS 桌面小组件。
本需求用于实现真正的 iOS 小组件（WidgetKit Extension），使用户可以在 iOS 桌面添加小组件并看到“情绪文字/正念短句”等内容。
目标
- 可添加到桌面：支持在 iOS 桌面添加小组件（WidgetKit）
- V1（本期）写死内容：小组件展示一段美观文案（先写死，不做数据同步/更新）
- 可点击跳转：点击小组件可跳转回 App 指定页面（默认 Home）
非目标（本阶段不做）
- 不承诺严格准点刷新（受 iOS 系统调度限制）
- 不做复杂的小组件交互配置（如需可后续拆分）
- 不要求 Android Widget（仅 iOS）
- V1 不做数据更新：不做 App -> Widget 数据共享与更新触发（App Group 留到后续版本）
2. 关键结论与约束（必须接受）
- Expo Go 不支持 WidgetKit：必须使用 Development Build / 预构建后的原生工程 / EAS Build 才能安装带小组件扩展的 App
- 需要原生扩展：iOS 小组件必须创建 WidgetKit Extension（SwiftUI）
- V1 不需要 App Group：因为内容写死在 Widget 内部；后续做数据共享时再引入 App Group
3. 小组件功能需求（高层）
3.1 展示内容
- 展示一段“情绪文字/正念短句”
- 背景支持：
- 纯色或渐变（优先）
- 图片（可选，后续）
- 文案需“美观可读”，适配暗色模式（可选）
3.2 尺寸支持
- 支持 iOS 常见尺寸：
- Small
- Medium
- Large
3.3 更新策略
V1：不做更新策略（内容写死）。后续版本可扩展：
- 固定间隔更新（例如每天/每小时）
- App 驱动更新：App 写入新内容，Widget 触发 reload（系统仍可能延迟）
3.4 点击跳转
- 点击小组件可打开 App 并跳转到指定页面：
- 默认：Home
- 可选：Favorites
4. 数据共享与持久化（高层）
V1：不做数据共享与持久化（写死文案）。
后续版本（V2）再引入 App Group（共享 UserDefaults）与数据来源策略：
widget.text、widget.updatedAt、widget.lang、widget.theme等- 数据来源可选：Home 当前/最近 Like/随机 mock
5. 多语言（与 App 一致）
- 语言码沿用客户端：
zh-CN/en/es/pt/zh-TW - V1：Widget 内可先写死单语（例如中文）或做最小的本地化（可选）
- V2：建议由 App 端选择语言并写入共享数据，降低 Widget 端 i18n 复杂度
6. 验收标准
- 可以在 iOS 桌面搜索并添加小组件
- 小组件能显示一段美观文案（至少支持 Small）
- 点击小组件能打开 App 并进入预期页面
7. 风险与注意事项
- iOS 刷新频率限制：不可承诺“每分钟刷新”等高频
- App Group / Bundle ID 配置错误会导致 Widget 读不到数据
- Dev Build / EAS 证书配置成本较高，需要在计划阶段明确落地路径