TimelineProvider

建议WidgetKit何时更新窗口小部件显示的类型。

protocol TimelineProvider

使用教程

在不同的时间，WidgetKit向提供者请求时间轴。时间线是符合TimelineEntry的对象数组。每个时间轴条目都有一个日期，您可以指定其他属性来显示小部件。
例如，考虑显示游戏角色健康等级的小部件。在游戏中，当角色的健康水平低于100％时，其恢复速度为每小时25％。如果角色的健康等级为25％，则提供商会创建一个包含四个条目的时间表：
当前时间，健康水平25％
从现在开始1小时，健康水平50％
从现在开始2个小时，健康水平达到75％
从现在开始3个小时，健康水平100％
以下代码显示了封装此信息的结构。

struct CharacterDetailEntry: TimelineEntry {
    var date: Date
    var healthLevel: Double
}

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

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

在瞬态情况下（例如，当用户添加窗口小部件时）显示窗口小部件时，WidgetKit会发出快照请求。 WidgetKit提供了一个上下文参数，其中包含有关如何使用该条目的详细信息，包括它是小部件库的预览，还是要显示的小部件的系列或大小。如果context.isPreview为true，则该小部件将出现在小部件库中，并且需要提供者的快速响应。如果生成快照所需的信息不可用，或者需要额外的时间来加载，请改用示例数据。例如，如果确定角色的健康等级需要从服务器获取数据，则小部件可以显示75％的健康等级。以下代码显示了游戏小部件如何实现其快照方法。

struct CharacterDetailProvider: TimelineProvider {
    func snapshot(with context: Context, completion: @escaping (Entry) -> ()) {
        let date = Date()
        let entry: CharacterDetailEntry

        if context.isPreview && !hasHealthLevel {
            entry = CharacterDetailEntry(date: date, healthLevel: 0.75)
        } else {
            entry = CharacterDetailEntry(date: date, healthLevel: currentHealthLevel)
        }
        completion(entry)
    }
}

用户从窗口小部件库中添加窗口小部件后，WidgetKit发出时间轴请求。由于您的窗口小部件扩展程序并不总是运行，因此WidgetKit需要知道何时激活它来更新窗口小部件。您的提供商生成的时间线会在您希望更新窗口小部件时通知WidgetKit。以下示例显示了角色的健康水平为25％时生成的时间轴。

struct CharacterDetailProvider: TimelineProvider {
    func timeline(with context: Context, completion: @escaping (Timeline<CharacterDetailEntry>) -> ()) {
        var date = Date()
        var healthLevel = 0.25
        var entries: [CharacterDetailEntry] = []

        while healthLevel <= 1 {
            // Add the current health level for a given date.
            entries.append(CharacterDetailEntry(date: date, healthLevel: healthLevel))

            // Health recovers at 25 percent per hour, with a maximum of 100 percent.
            healthLevel = min(1, healthLevel + 0.25)

            // Move the date forward by 1 hour.
            date = Calendar.current.date(byAdding: .hour, value: 1, to: date)!
        }

        // Create the timeline and call the completion handler.
        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    }
}

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

确定刷新策略

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

// Request a timeline refresh after 2.5 hours.
let date = Calendar.current.date(byAdding: .minute, value: 150, to: Date())
let timeline = Timeline(entries: entries, policy: .after(date))
completion(timeline)

使用不同日期的其他例子包括：

在显示股市详细信息的小部件中，您可以指定下一个市场开市或收市日期，因为信息通常不会在一夜之间或在周末期间发生变化。
飞行着陆后，飞行跟踪小部件可能会继续显示“飞行着陆”指示。在这种情况下，您可以指定一个日期，而不是在航班降落之后指定日期，以便其状态在清除之前的一段时间内保持可见状态。
或者，如果将来的事件不可预测，则可以通过为策略指定.never来告诉WidgetKit根本不请求新的时间轴。在这种情况下，当有新的时间轴可用时，您的应用程序将调用WidgetCenter函数reloadTimelines（ofKind :)。使用.never有意义的一些示例包括：
当用户拥有配置为显示角色健康状况的小部件，但该角色不再积极参与战斗并且其健康水平不会改变时。
窗口小部件的内容取决于用户是否已登录帐户而当前尚未登录。
在这两个示例中，当您的应用确定状态已更改时，它将调用WidgetCenter函数reloadTimelines（ofKind :)，并且WidgetKit请求新的时间轴。

SwiftUI Widgets 之02 TimelineProvider 基础概念

SwiftUI Widgets 之02 TimelineProvider 基础概念

TimelineProvider

使用教程

确定刷新策略

使用不同日期的其他例子包括：

推荐

基础文章推荐

经典教程推荐

技术源码推荐

推荐文章

CoreData篇

Combine篇

TextField篇

JSON文件篇

一篇文章系列

技术交流