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