2021 - 43周（Widget入门）_swift widget timelineentry-优快云博客

Provider：一个遵循TimelineProvider协议的对象，它会提供一个timeline来告诉WidgetKit何时渲染widget。一个timeline包含一个你自定义的TimelineEntry类型。TimelineEntry声明了你想要WidgetKit更新widget的时间和你的widget的view需要渲染使用的属性。
Content Closure：一个包含SwiftUI视图的闭包，WidgetKit引用这个来渲染widget的内容，并传递给视图TimelineEntry的参数
Custom Intent：自定义Intent来定义用户可配置属性（具体见可配置Widget）

使用modifiers提供额外配置信息，包括：

Widget名称：configurationDisplayName
描述：description
支持的大小：supportedFamilies（大、中、小）

//Widget设置 —— 来自苹果官方文档的示例
@main
struct GameStatusWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "com.mygame.game-status",
            provider: GameStatusProvider(),
        ) { entry in
            GameStatusView(entry.gameStatus)
        }
        .configurationDisplayName("Game Status")
        .description("Shows an overview of your game status")
        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
    }
}

注意：

用户至少要在安装后启动一次app，才能使得app关联的widget在系统的小组件列表中展示

3.提供Timeline Entries

Timeline entry提供更新widget的时间和数据。遵循TimelineEntry协议。

WidgetKit会向provider索要占位图，此图会展示在widget列表中（非主屏幕，见下图）。

通过getSnapshot(in:completion:)方法中传入的context参数的isPreview变量可以判断当前视图是否是占位图。占位图要快速生成，不要占用太长生成时间，可以考虑使用示例数据

//getSnapshot函数实现，提供占位视图 —— 来自苹果官方文档的示例
truct GameStatusProvider: TimelineProvider {
    var hasFetchedGameStatus: Bool
    var gameStatusFromServer: String

    func getSnapshot(in context: Context, completion: @escaping (Entry) -> Void) {
        let date = Date()
        let entry: GameStatusEntry

        if context.isPreview && !hasFetchedGameStatus {
            entry = GameStatusEntry(date: date, gameStatus: "—")
        } else {
            entry = GameStatusEntry(date: date, gameStatus: gameStatusFromServer)
        }
        completion(entry)
    }

之后WidgetKit调用 getTimeline(in:completion:)来向provider请求timeline的规则。Timeline由一个或多个timeline entry组成，同时包含一个说明何时请求下一次timeline的更新规则。下例中展示了包含一个entry并声明更新规则为15分钟后触发下次请求的getTimeline方法

//getTimeline方法包含了timeline entry和15分钟后更新的规则 —— 来自苹果官方文档的代码
struct GameStatusProvider: TimelineProvider {
    func getTimeline(in context: Context, completion: @escaping (Timeline<GameStatusEntry>) -> Void) {
        // Create a timeline entry for "now."
        let date = Date()
        let entry = GameStatusEntry(
            date: date,
            gameStatus: gameStatusFromServer
        )

        // Create a date that's 15 minutes in the future.
        let nextUpdateDate = Calendar.current.date(byAdding: .minute, value: 15, to: date)!

        // Create the timeline with the entry and a reload policy with the date
        // for the next update.
        let timeline = Timeline(
            entries:[entry],
            policy: .after(nextUpdateDate)
        )

        // Call the completion to pass the timeline to WidgetKit.
        completion(timeline)
    }
}

4.提供占位图（主页面）

Widget被首次添加到主屏幕的时候，WidgetKit会使用占位图渲染它，通过调用placeholder(in:)方法来获取占位图信息。

//展示于桌面的占位图 —— 来自苹果官方文档的示例
struct GameStatusProvider: TimelineProvider {
    func placeholder(in context: Context) -> SimpleEntry {
        GameStatusEntry(date: Date(), gameStatus: "—")
    }
}

5.展示Widget的内容

使用SwiftUI来定义页面，需要提供你的widget支持的所有大小的页面。

//SwiftUI定义页面 —— 来自苹果官方文档的示例
struct GameStatusView : View {
    @Environment(\.widgetFamily) var family: WidgetFamily
    var gameStatus: GameStatus

    @ViewBuilder
    var body: some View {
        switch family {
        case .systemSmall: GameTurnSummary(gameStatus)
        case .systemMedium: GameStatusWithLastTurnResult(gameStatus)
        case .systemLarge: GameStatusWithStatistics(gameStatus)
        default: GameDetailsNotAvailable()
        }
    }
}

注意：

Widget展示的是“只读”信息，不支持交互组件（如：滚动控件），WidgetKit会在渲染的时候忽略交互组件

6.添加动态内容

尽管widget是基于你的view的一个截图，但你仍然可以使用各种SwiftUI组件来持续更新它。详见：Keeping a Widget Up To Date。

Widget可以通过Userdefault或者文件系统与app共享数据，使用Userdefault的话，需要在app中添加App Groups，然后使用App Group来初始化Userdefault。

NSUserDefaults *userDef = [[NSUserDefaults alloc] initWithSuiteName:@"group.yourappgroup"];

//初始化UserDefaults

7.用户交互

当用户点击widget，系统会打开你的app。Widget可以通过一个URL来通知app具体跳转到哪个模块。

对于三种大小的widget，他们支持的交互方式不同

小（systemSmall）只支持widgetURL(_:)方式

中（systemMedium）和大（systemLarge）除了支持widgetURL(_:)方式，还可以通过添加Link的方式添加跳转

//通过widgetURL为widget添加跳转交互 —— 来自苹果官方文档的示例
@ViewBuilder
var body: some View {
    ZStack {
        AvatarView(entry.character)
            .widgetURL(entry.character.url)
            .foregroundColor(.white)
    }
    .background(Color.gameBackground)
}

App端通过onOpenURL(perform:), application(_:open:options:), or application(_:open:)等系统方法来获取到widget传入的跳转链接

8.添加多个Widget

为了支持多Widget，你需要添加支持WidgetBundle协议的结构体，在该结构体中把多个widget聚合到它的body属性中

//多Widget —— 来自苹果官方的示例
@main
struct GameWidgets: WidgetBundle {
    @WidgetBundleBuilder
    var body: some Widget {
        GameStatusWidget()
        CharacterDetailWidget()
        LeaderboardWidget()
    }
}