85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
# 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 证书配置成本较高，需要在计划阶段明确落地路径
|
||
|