用途:用 RelevanceKit 告诉 Apple Watch 智能叠放某小组件在何时重要,依据包括时间、位置、健身状态、睡眠计划或已连接硬件。目标为 Swift 6.3 和 watchOS 26+ 相关小组件流程,属测试敏感内容,改动可用性、签名或智能叠放行为前需重新核对 Apple 文档。
提供者模型:一是给现有 AppIntentTimelineProvider 添加 relevance(),适合小组件始终有时间线内容、相关度仅作补充;二是使用 RelevanceConfiguration 配合 RelevanceEntriesProvider,适合仅在匹配条件下出现或生成多张相关卡片,此路径要求 watchOS 26+。RelevantContext 跨 Apple 平台声明,但相关度效果仅限 watchOS。
边界:本技能聚焦 RelevantContext、WidgetRelevanceAttribute、provider relevance()、RelevanceConfiguration、分组、RelevantIntentManager 及相关权限。小组件时间线、族、重载预算、渲染、推送重载、实时活动与控件归 widgetkit;锻炼会话、活动/睡眠查询、路线与 HealthKit 授权归 healthkit;地理编码、地点搜索、路线、区域、地理围栏与定位授权架构归 mapkit。
信号与权限:.date(...) 表示时刻、日程事件或日期区间,无需额外设置;.location(inferred:) 表示家、工作、学校、通勤,需应用定位权限加 NSWidgetWantsLocation;.location(_:) 指定 CLRegion,.location(category:) 表示附近兴趣点类别(返回可选),均需相同定位设置;.fitness(.workoutActive) 需 HealthKit 读取 HKWorkoutType,.fitness(.activityRingsIncomplete) 需精确的锻炼/活动/站立读取类型;.sleep(...) 需睡眠分析读取权限;.hardware(headphones:) 无需设置。定位用途字符串放在宿主应用;小组件扩展声明 NSWidgetWantsLocation 并检查 CLLocationManager.isAuthorizedForWidgetUpdates;每个提供健身或睡眠相关度的目标都需启用 HealthKit 并请求精确读取类型。
提供者不变量:WidgetRelevanceAttribute 按优先级返回,系统可能只用其中一部分;location(category:) 为可选,不支持时省略而非强制解包;相关条目提供者应提供 relevance、entry、placeholder 与确定性的预览路径;时间线与相关小组件表示同一数据时用 .associatedKind(_:) 避免智能叠放重复卡片;分组使用 .automatic、.ungrouped 或 .named 需有明确意图;时间线提供者相关度在源数据变化时就调用 RelevantIntentManager.shared.updateRelevantIntents,而非只在时间线刷新时;授权缺失时优雅降级,不伪造位置、健身或睡眠线索。
测试与常见错误:在 Apple Watch 上开启 WidgetKit 开发者模式,按相关显示尺寸预览 entry 与配置状态,覆盖权限已授予、拒绝、受限与数据不可用路径,用真实条目验证排序、分组与去重,最后在实体手表上完成,不要以编译通过或 iOS 预览行为作为智能叠放排序的证明。常见错误包括:期望 RelevanceKit 调用影响 iOS 小组件排序;在普通时间线加相关度已足够时创建相关小组件;无小组件更新授权就返回位置线索;源数据变化后未刷新相关意图;遗漏 associatedKind 造成重复卡片;假设每个兴趣点类别都会生成上下文。
复查清单:提供者模型与“始终可用”还是“仅条件出现”匹配;相关度范围与 WidgetKit、HealthKit、MapKit 职责分离;每条线索都有精确权限与可用性设置;属性按优先级排序并省略不支持的可选项;entry、placeholder、relevance 与预览路径确定性;分组与 associatedKind 防止多余重复;底层数据变化时相关意图更新;实体手表测试覆盖权限与排序行为。参考资料包括 RelevanceKit patterns、RelevanceKit documentation、RelevantContext、Smart Stack widget suggestions、RelevanceConfiguration、RelevanceEntriesProvider。