PAYATHON 2026

AppIntentConfiguration 编辑页已选 AppEntity 显示过期

数据小陈

结论

从目前公开 API 和这个现象来看,问题更可能出在系统配置 UI 对已选 AppEntity 的 DisplayRepresentation 做了归档或缓存。你的 EntityStringQuery 应该没写错。WidgetCenter.shared.reloadTimelines(ofKind:) 只会让 WidgetKit 重载 timeline,不会刷新“编辑 Widget”sheet 里已选参数行的显示标签。公开 API 里也没有类似 reloadConfiguration 的接口,能主动让系统重新解析这一行。

原因

  • entities(for:)、entities(matching:)、suggestedEntities() 主要用于选择列表和搜索;列表能显示新名称,说明取数路径正常。
  • 已选参数行是系统保存的 widget 配置的一部分。系统保存配置时可能已经把当时的 DisplayRepresentation 归档下来,之后打开编辑页就直接展示缓存值。
  • Widget 内容刷新和配置 UI 刷新走的是两条路径。重新加载 timeline 不会改写已有的 widget 配置。
  • 不同 iOS 版本刷新这个缓存的时机可能不一样,别指望每次打开编辑页都会重新调用 displayRepresentation。

可行处理

  1. 别把编辑页的已选行当成实时数据展示位。在 Widget 视图里用稳定 ID 重新查当前名称,保证主界面显示正确。
struct BalanceWidgetView: View {
    let entry: BalanceTimelineEntry

    var body: some View {
        let name = MutualWidgetStore.contactName(for: entry.contactID) ?? "Contact"
        VStack {
            Text("Mutual Balance")
            Text(name)
        }
    }
}
  1. 如果产品要求编辑页也显示新名称,只能让用户重新选一次这个参数再保存,或者删掉 widget 后重新添加。重新保存配置会让系统写入新的显示快照;App 端没法通过 WidgetCenter 直接改已有配置。

  2. 如果不想让用户看到“旧名字”这种明显过期的信息,可以把已选 AppEntity 的显示文案改成稳定标签,真实名称放到 widget 内容里。例如:

var displayRepresentation: DisplayRepresentation {
    DisplayRepresentation(title: "Contact")
}

这样编辑页不会显示具体的旧名称,选择列表和 widget 仍然能用 ID 查最新数据。代价是编辑页的信息量会少一些。

  1. 可以加日志,确认打开编辑页时 entities(for:) 到底有没有被调用:
func entities(for identifiers: [String]) async throws -> [BalanceSelectionEntity] {
    print("entities(for:) identifiers=\(identifiers)")
    return MutualWidgetStore.contacts()
        .filter { identifiers.contains($0.id) }
        .map { BalanceSelectionEntity(contact: $0) }
}

如果日志没打印,说明系统直接用了缓存;如果打印了但行标签还是旧的,说明显示标签仍被系统层缓存。这两种情况都不是 query 取数的问题。

注意事项

  • 保持 AppEntity.id 稳定。不要为了刷新显示,把名称或 hash 拼进 id,这会破坏已有配置和选择匹配。
  • WidgetCenter.shared.reloadTimelines(ofKind:) 和 reloadAllTimelines() 都不负责刷新编辑 sheet。
  • 如果这个功能要支持多个 iOS 版本,需要在目标系统的真机上验证编辑页行为;不要假设所有版本都会重新解析已选行。
  • 目前更稳妥的产品设计是:编辑页显示稳定或概括性的标签,widget 视图显示实时数据。

备注:内容仅供参考。