6c6a950140
feat: 添加拍药盒功能和语音直达入口 - 实现拍药盒扫描流程，支持本地OCR识别药品信息 - 在日记页面添加拍药盒和记症状的三选一入口 - 优化按钮点击区域，确保符合苹果HIG最小命中区标准 - 添加用药记录到时间线的独立分类显示 - 实现长按+号语音直达功能，支持语音意图分类跳转 - 更新项目配置文件，启用代码分析和死代码剥离选项 - 增加多项本地化字符串支持新功能 ```
53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
# 桌面 Widget 接入步骤（约 3 分钟，Xcode 操作）
|
||
|
||
代码已全部写好。主 App 侧（快照写入 + RootView hook）已自动编译生效；
|
||
Widget extension 需要你在 Xcode 里建一次 target，再放入两个源文件。
|
||
|
||
## 1. 创建 Widget Extension target
|
||
|
||
1. Xcode 打开 `康康.xcodeproj` → 菜单 **File → New → Target…**
|
||
2. 选 **iOS → Widget Extension**，点 Next
|
||
3. Product Name 填 **`KangkangWidget`**
|
||
- ❌ 不勾 "Include Live Activity"（W5 做 Live Activity 时再往这个 target 里加，Bundle 入口已留好注释）
|
||
- ❌ 不勾 "Include Configuration App Intent"（我们用 StaticConfiguration）
|
||
4. 点 Finish；弹出 "Activate scheme?" 选 **Activate**
|
||
|
||
## 2. 替换模板代码
|
||
|
||
Xcode 会在工程根目录生成 `KangkangWidget/` 文件夹（含模板 swift 文件）。
|
||
|
||
1. 删除模板生成的所有 `.swift` 文件（`KangkangWidget.swift`、`KangkangWidgetBundle.swift`、`AppIntent.swift` 等，**保留 `Info.plist` 和 Assets**），选 "Move to Trash"
|
||
2. 把 `KangkangWidget-src/` 里的两个文件拖进 Xcode 的 `KangkangWidget` 文件夹（勾选 target：KangkangWidget）：
|
||
- `KangkangWidgetBundle.swift`
|
||
- `PinnedIndicatorsWidget.swift`
|
||
3. 拖完后可删掉暂存目录 `KangkangWidget-src/`
|
||
|
||
## 3. 配置 App Group（两个 target 都要）
|
||
|
||
数据通过 App Group UserDefaults 传递，ID 固定为 **`group.com.xuhuayong.kangkang`**。
|
||
|
||
1. 选中工程 → target **康康** → Signing & Capabilities → **+ Capability → App Groups** → ＋ 添加 `group.com.xuhuayong.kangkang`
|
||
2. target **KangkangWidget** → 同样添加 App Groups → 勾选同一个 `group.com.xuhuayong.kangkang`
|
||
3. KangkangWidget 的 **iOS Deployment Target 改成 17.0**（模板默认可能更高）
|
||
|
||
> 个人开发者账号下 App Group 会自动注册；如签名报错，在两个 target 的 Signing 里确认 Team 一致。
|
||
|
||
## 4. 验证
|
||
|
||
1. scheme 切回 **康康**，跑真机/模拟器
|
||
2. 进 App（首页出现即写入快照），回到桌面 → 长按 → 添加小组件 → 找 **康康 · 长期监测**
|
||
3. 小/中两个尺寸都支持。没有任何 pinned 指标时显示引导文案；
|
||
在趋势页关注指标（或 C2「关联到趋势」）后，回桌面即可看到最新值
|
||
|
||
## 故障排查
|
||
|
||
- **小组件空白/不出现**：先确认两个 target 的 App Group 勾的是同一个 ID；再确认主 App 至少前台打开过一次（快照由主 App 写）
|
||
- **数据不更新**：快照在 App 进后台时刷新；强杀 App 不触发 `scenePhase == .background`，正常 Home 手势退出即可
|
||
- **编译报 `containerBackground` 不存在**：KangkangWidget 的 Deployment Target 没改成 17.0
|
||
|
||
## 架构备忘（给后续会话）
|
||
|
||
- 主 App 写快照：`康康/Persistence/WidgetSnapshot.swift`（数据契约）+ `WidgetSnapshotRefresher.swift`（pinned 指标 → App Group，RootView 在启动和进后台时调用）
|
||
- Widget 读快照：`KangkangWidget/PinnedIndicatorsWidget.swift` 内有 `WidgetSnapshot` 的**独立拷贝**（extension 不引主 App 代码）。⚠️ 改字段两边同步
|
||
- Widget 不读 SwiftData：store 有文件保护且在主 App 沙盒，extension 锁屏时读不到；快照 = 最后一次看到的值，锁屏也能显示
|