widgetkit-code-review

WidgetKit 代码审查

快速参考

问题类型	参考资料
TimelineProvider、entries、重新加载策略	references/timeline.md
Widget family、containerBackground、深层链接	references/views.md
AppIntentConfiguration、EntityQuery、@Parameter	references/intents.md
刷新预算、内存限制、缓存	references/performance.md

审查清单

• placeholder(in:) 立即返回，不执行异步操作
• Timeline 条目之间至少间隔 5 分钟
• getSnapshot 检查 context.isPreview，以支持图库预览
• 使用 containerBackground(for:) 以兼容 iOS 17+
• systemSmall 使用 widgetURL（而非 Link）
• 不使用 Button 视图（改用 Link 或 widgetURL）
• Widget 视图中不使用 AsyncImage 或 UIViewRepresentable
• 图像已缩小采样至 Widget 显示尺寸（约 30MB 限制）
• 已配置 App Groups，以便在应用和 Widget 之间共享数据
• 对于非可选参数，EntityQuery 实现 defaultResult()
• 更新后，新的 intent 参数能处理现有 Widget 中的 nil 值
• 策略性地调用 reloadTimelines（而非每次数据变化时都调用）

何时加载参考资料

• TimelineProvider 实现或刷新问题 -> timeline.md
• Widget 尺寸、锁定屏幕、containerBackground -> views.md
• 可配置 Widget、AppIntent 迁移 -> intents.md
• 内存问题、缓存、预算管理 -> performance.md

审查问题

1. 系统延迟刷新时，Widget 是否提供备用条目？
2. 是否妥善处理锁定屏幕的 family（accessoryCircular/Rectangular/Inline）？
3. 从 IntentConfiguration 迁移是否会导致现有用户的 Widget 无法正常工作？
4. Timeline 是否填充了未来的条目，还是依赖频繁刷新？
5. 是否通过 App Groups 缓存数据，以供 Widget 访问？

硬性关卡（报告前）

对于每项拟报告的问题，必须按顺序完成以下步骤。满足通过条件前，不得进入下一步。

1. 位置凭据 — 问题中包含从当前文件内容复制的 [FILE:LINE]（或行范围）；该路径在此仓库中有效。
2. 读取相关代码范围 — 阅读完整的周边实现：TimelineProvider（包括相关的 placeholder、getSnapshot 和 getTimeline）、@main Widget / Widget bundle，或可配置 Widget 的 AppIntentConfiguration / intent 类型，而不只是 diff 片段或代码片段。
3. 平台或系统声明（仅当问题依赖刷新预算、约 30MB 的内存建议、锁定屏幕 accessory family、iOS 17+ 的 containerBackground、App Groups 数据共享，或从 IntentConfiguration 迁移至 AppIntentConfiguration 时）— 指明一个已检查的具体凭据（例如项目中的 .entitlements / App Group id、源码中的 WidgetFamily 处理、IPHONEOS_DEPLOYMENT_TARGET，或所用参考资料的确切小节），或者将该问题删除或降级为开放问题。
4. 协议 — 此项必须满足 review-verification-protocol 中针对该审查类型的报告前步骤；若未满足，不得报告问题。

每项报告的问题使用格式 [FILE:LINE] ISSUE_TITLE。硬性关卡 4 是此审查类型的完整报告前检查清单。