TimelineProvider Protocol

TimelineProvider

一个通知WidgetKit何时更新的类型。

定义

  1. protocol TimelineProvider

概述

在不同的时候，WidgetKit会向提供者请求一个时间线。

时间线是一个符合TimelineEntry的对象数组。

每个时间线条目都有一个日期，你可以指定显示小组件的附加属性。

例如，考虑一个显示游戏角色健康水平的小组件。在游戏中，当角色的健康水平低于100%时，它将以每小时25%的速度恢复。如果角色的健康水平为25%，提供者就会创建一个由四个条目组成的时间轴。

  • 当前时间，健康水平25%
  • 1小时后，健康水平50%
  • 2小时后，健康水平75%
  • 3小时后，健康水平100%

以下代码显示了封装此信息的struct。

  1. struct CharacterDetailEntry: TimelineEntry {
  2.     var date: Date
  3.     var healthLevel: Double
  4. }

WidgetKit 通过以下两种方式之一请求时间轴条目：

  1. 单个即时快照，代表小部件的当前状态。
  2. 一系列条目，包括当前时刻以及小部件状态将改变的任何将来的日期（如果知道）。

在瞬态情况下（例如，当用户添加窗口小部件时）显示窗口小部件时，WidgetKit 会发出快照请求。 WidgetKit 提供了一个上下文参数，其中包含有关如何使用条目的详细信息，包括它是小部件库的预览，还是要显示的小部件的系列或规格。如果 context.isPreview 为 true，则该小部件将出现在小部件库中，并且需要provider的快速响应。

如果生成快照所需的信息不可用，或者需要额外的时间来加载，请改用示例数据。例如，如果确定角色的健康等级需要从服务器获取数据，则小部件可以显示 75％的健康等级。以下代码显示了游戏小部件如何实现其快照方法。

  1. struct CharacterDetailProvider: TimelineProvider {
  2.     func snapshot(with context: Context, completion: @escaping (Entry) -> ()) {
  3.         let date = Date()
  4.         let entry: CharacterDetailEntry
  6.         if context.isPreview && !hasHealthLevel {
  7.             entry = CharacterDetailEntry(date: date, healthLevel: 0.75)
  8.         } else {
  9.             entry = CharacterDetailEntry(date: date, healthLevel: currentHealthLevel)
  10.         }
  11.         completion(entry)
  12.     }
  13. }

用户从窗口小部件库中添加窗口小部件后，WidgetKit 发出时间轴请求。 由于您的窗口小部件扩展程序并不总是运行，因此 WidgetKit 需要知道何时激活它来更新窗口小部件。 您的provider生成的时间线会在您希望更新窗口小部件时通知 WidgetKit。

以下示例显示了角色的健康水平为 25％时生成的时间轴。

  1. struct CharacterDetailProvider: TimelineProvider {
  2.     func timeline(with context: Context, completion: @escaping (Timeline<CharacterDetailEntry>) -> ()) {
  3.         var date = Date()
  4.         var healthLevel = 0.25
  5.         var entries: [CharacterDetailEntry] = []
  7.         while healthLevel <= 1 {
  8.             // 添加给定时间的当前健康级别。
  9.             entries.append(CharacterDetailEntry(date: date, healthLevel: healthLevel))
  11.             // 生命每小时恢复 25％，最多恢复 100％。
  12.             healthLevel = min(1, healthLevel + 0.25)
  14.             // 将时间往后 1 小时。
  15.             date = Calendar.current.date(byAdding: .hour, value: 1, to: date)!
  16.         }
  18.         // 创建时间轴并调用完成处理程序。
  19.         let timeline = Timeline(entries: entries, policy: .atEnd)
  20.         completion(timeline)
  21.     }
  22. }

如果您的provider需要执行异步工作来生成时间线（例如，从服务器获取数据），请存储对完成处理程序的引用，并在完成异步工作后调用它。

确定刷新策略

创建时间轴时，provider会指定一个刷新策略，该策略控制 WidgetKit 请求新时间轴的时间。

默认行为是使用.atEnd 在时间轴中的条目指定的最后日期之后请求新的时间轴。 但是，如果 WidgetKit 请求新时间轴的日期不同，则可以将刷新策略指定为.after（date :)。 例如，一条龙将在 2.5 小时后出现，并可能与游戏角色进行战斗。 由于战斗的结果可能会改变角色的健康状况，因此提供者可以告诉 WidgetKit 在战斗后请求新的时间表。

  1. // 请求2.5小时之后刷新时间轴
  2. let date = Calendar.current.date(byAdding: .minute, value: 150, to: Date())
  3. let timeline = Timeline(entries: entries, policy: .after(date))
  4. completion(timeline)

使用不同的日期是有意义的。

例子包括：

  1. 在显示股市详情的小组件中，您可以指定下一个市场开盘或收盘日期，因为信息通常不会在一夜之间或周末发生变化。

  2. 航班跟踪小组件可能会在航班降落后继续显示 “航班降落 “指示。在这种情况下，您可以指定一个比航班降落时间晚的日期，这样在被清除之前，它的状态就会保持一段时间可见。

另外，如果未来的事件是不可预测的，你可以通过为策略指定.never来告诉WidgetKit完全不请求新的时间线。在这种情况下，当有新的时间线可用时，你的应用程序会调用WidgetCenter函数reloadTimelines(ofKind:)。

一些使用.never例子包括。

  • 当用户拥有一个配置为显示角色健康状况的小组件，但该角色不再积极参与战斗，其健康水平不会改变。
  • 当小组件的内容取决于用户是否登录账户，而他们当前没有登录时。

在这两个例子中，当你的应用确定状态发生变化时，它会调用WidgetCenter函数reloadTimelines(ofKind:)，WidgetKit会请求一个新的时间线。

Topics

Generating Timelines

  • func snapshot(with: Self.Context, completion: (Self.Entry) -> ()))

    • 提供一个时间轴条目，表示小组件的当前时间和状态。「必须」

  • func timeline(with: Self.Context, completion: (Timeline) -> ())

    • 提供当前时间的时间线条目数组，并可选择提供任何未来时间以更新小组件。「必须」

  • associatedtype Entry : TimelineEntry

    • 「必须」

Type Aliases

  • typealias Context