iOS 14 Widget小组件

iOS14带来了新的UI组件：WidgetKit，前身是iOS10时候引入的Today Extension。

一、创建Widget

通过Xcode -> File -> New -> Target菜单路径找到 Widget Extension，双击创建

这里勾选为用户可配置的小程序，不勾选为不可配置。详见本文第四部分。

二、解读代码

1. Provider

为小组件展示提供一切必要信息的结构体，实现TimelineProvider协议

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> SimpleEntry { ...... }
    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> Void) { ...... }
    func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) { ...... }
}

placeholder：提供一个默认的视图，当网络数据请求失败或者其他一些异常的时候，用于展示
getSnapshot：为了在小部件库中显示小部件，WidgetKit要求提供者提供预览快照，在组件的添加页面可以看到效果
getTimeline：在这个方法内可以进行网络请求，拿到的数据保存在对应的entry中，调用completion之后会到刷新小组件。
请求时间线有两个地方：一个是按照策略请求，一个在请求即时快照时。
刷新小组件并不能重新获取展示数据，只有重启时间线，才能重新获取数据。
如果需要定义小组件的刷新策略为每分钟刷新，15分钟后重启时间线：

//设置时间线
    func getTimeline(in context: Context, completion: @escaping (Timeline) -> ()) {
        var entries: [SimpleEntry] = []
        
        let currentDate = Date()
        for hourOffset in 0 ..< 15 {
            //设置刷新策略
            let entryDate = Calendar.current.date(byAdding: .minute, value: hourOffset, to: currentDate)!
            entries.append(simpleModel(entryDate))
        }
        //重启时间线策略
        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    }

关于重启策略，根据官方文档，每个配置的小部件每天接收有限的重启次数。有几个因素会影响小部件接收的重启次数，例如：包含的应用程序是在前台还是后台运行，小部件在屏幕上显示的频率，以及包含的应用程序参与的活动类型。
根据我参考其他开发者的分享，设定在5分钟以下的重启时间线策略几乎无效。一般设定在15分钟以上的策略，才能按时重启时间线。
策略有如下几种：

//在结束时重启

public static let atEnd: TimelineReloadPolicy

//从不重启

public static let never: TimelineReloadPolicy

//在某一时间点后重启

public static func after(_ date: Date) -> TimelineReloadPolicy

2. SimpleEntry

实现TimelineEntry协议，就是用来保存所需要的数据。
其中TimelineEntry含有date属性。
可以继续添加其他的属性。例如自定义一个展示用的model：

struct Model {
    let Title: String
    let Image: UIImage
    let ID: String
    let Context: String
}

将Model添加到entry中

struct SimpleEntry: TimelineEntry {
    let date: Date
    let Obj1: Model
    let Obj2: Model
    let Obj3: Model
}

3. 加载入口

YourWidget是我们为组件设置的名字，模板自动使用这个名字帮我们生成了一个实现了Widget协议的结构体。

struct YourWidget: Widget {
    let kind: String = "YourWidgetKind"
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            YourWidgetEntryView(entry: entry)
        }
        .configurationDisplayName("---")
        .description("---")
    }
}

StaticConfiguration是系统提供的组件配置结构体，其用来对静态类型的组件提供配置。
kind：是Widget的唯一标识
StaticConfiguration：初始化配置代码
configurationDisplayName：添加编辑界面展示的标题
description：添加编辑界面展示的描述内容
supportedFamilies这里可以限制要提供三个样式中的哪几个

一个Widget只提供了三个样式的选择：大、中、小
如果需要展示多个Widget(最多5个):

struct YourWidgets: WidgetBundle {
    @WidgetBundleBuilder
    var body: some Widget {
        Widget()
        Widget2()
        ......
    }
}

4. SwiftUI展示UI

VStack:垂直排列元素
HStack:水平排列元素
ZStack:堆叠排列元素
显示文本方法：

Text(entry. Obj1.Title)
.font(.system(size: 18))
.fontWeight(.bold)

显示图片方法：

Image(uiImage: entry. Obj1.Image)
.resizable()
.frame(width: 50, height: 50)

三、Widget与App交互及获取数据

1. 唤起APP跳转

systemSmall只能用widgetURL修饰符实现URL传递:

ZStack(content: {
    Image(...)
    VStack(alignment: .leading, spacing: 4) {
        Text("...")
    }
})
.widgetURL(URL(string: "abc://..."))

systemMedium、systemLarge可以用Link或者 widgetUrl处理:

Link(destination: URL(string: "abc://...")!){
    HStack(content: {
        Image(...)
        VStack(alignment: .leading, spacing: 4) {
            Text(...)
            Text(...)
        }
    })
}

2. 主App传值到Widget

先使用开发者账号创建主App与Widget的group，生成groupid;
通过NSUserDefault或NSFileManager进行通信;
App存值：

NSUserDefaults *userDefaults = [[NSUserDefaults alloc] initWithSuiteName:@"groupId"];
[userDefaults setObject:dict forKey:key]];

Widget取值：

//从UserDefault中取值
func simpleModel(_ entryDate:Date) -> SimpleEntry
{
    let object1: NSDictionary = UserDefaults(suiteName: "groupId")?.object(forKey: key1) as! NSDictionary
    //可以继续添加obj2、obj3
    return SimpleEntry(date: Date(), object: object1)
}

3. 加载网络图片

无法异步加载图片，只能同步加载

let Image:UIImage = {
    if let iamgeData = try? Data(contentsOf: URL(string: “...” as!String)!) {
        return UIImage(data: iamgeData)!
    }
    return UIImage(named: "")!
}()

4. 网络请求

static func request(completion: @escaping (Result) -> Void) {
    let url = URL(string: "...")!
    let task = URLSession.shared.dataTask(with: url) { (data, response, error) in
        guard error == nil else {
            completion(.failure(error!))
            return
        }
        let poetry = getDataFromJson(fromData: data!)
        completion(.success(poetry))
    }
    task.resume()
}

static func getDataFromJson(fromData data: Data) -> SimpleEntry {
    let json = try! JSONSerialization.jsonObject(with: data, options: []) as! [String: Any]
    //因为免费接口请求频率问题，如果太频繁了，请求可能失败，这里做下处理，放置crash
    guard let data = json["data"] as? [String: Any] else {
        return SimpleEntry(加载失败的数据)
    }
    return SimpleEntry(...)
}

5. App主动刷新Widget

因为主动刷新小组件，仅支持swift。所以如果在OC原生环境中使用，需加入swift作为桥接。
创建 WidgetKitManager.swift文件

import WidgetKit

@objc
@available(iOS 14.0, *)
class WidgetKitManager: NSObject {

    @objc
    static let shareManager = WidgetKitManager()
    
    /// MARK: 刷新所有小组件
    @objc
    func reloadAllTimelines() {
        #if arch(arm64) || arch(i386) || arch(x86_64)
         WidgetCenter.shared.reloadAllTimelines()
        #endif
    }

    /// MARK: 刷新单个小组件
    /*
     kind: 小组件Configuration 中的kind
     */
    @objc
    func reloadTimelines(kind: String) {
        #if arch(arm64) || arch(i386) || arch(x86_64)
         WidgetCenter.shared.reloadTimelines(ofKind: kind)
        #endif
    }
}

OC中使用刷新小组件：

if (@available(iOS 14.0, *)) {
    //刷新所有小组件
    [[WidgetKitManager shareManager] reloadAllTimelines];
    //刷新单个小组件
    [[WidgetKitManager shareManager] reloadTimelinesWithKind:@"KindId"];
}

四、用户属性配置

在第一次创建Widget的时候，有一个选项我们没有勾选，Include Configuration Intent。这选项主要是用来支持你自定义一些属性配置（例如天气组件，用户可以选择城市，股票组件，用户可以选择代码等）

1. 补充创建

菜单File ->New ->File然后找到Siri Intent Definition File之后添加到Widget中.
这里一定记得勾选。

添加Intent

将属性改为：

此时系统会根据你的命名生成一个只读文件：

2. 设置可配置选项

这个选项设置完，就在上图中的代码上会有对应显示。

3. 修改代码

import Intents

SimpleEntry添加ConfigurationIntent属性

//从UserDefault中取值
func simpleModel(_ entryDate:Date, config:ConfigurationIntent) -> SimpleEntry
{
    let object1: NSDictionary = UserDefaults(suiteName: "......")?.object(forKey: "......") as! NSDictionary
    let object2: NSDictionary = UserDefaults(suiteName: "......")?.object(forKey: "......") as! NSDictionary
    let object3: NSDictionary = UserDefaults(suiteName: "......")?.object(forKey: "......") as! NSDictionary
    
    return SimpleEntry(date: Date(), configuration: config, Obj1: buildModel(object1), Obj2: buildModel(object2), Obj3: buildModel(object3))
}

//获取显示数据
func buildModel(_ dict:NSDictionary) -> Model
{
    let modelImage:UIImage = {
        if let iamgeData = try? Data(contentsOf: URL(string: dict.object(forKey: "ImageUrl") as!String)!) {
            return UIImage(data: iamgeData)!
        }
        return UIImage(named: "")!
    }()
    let Model = WistTVModel(
        Title: dict.object(forKey: "title") as! String,
        Image: modelImage,
        ID: dict.object(forKey: "ID") as! String,
        Context: dict.object(forKey: "Context") as! String
    )
    return Model
}

struct SimpleEntry: TimelineEntry {
    let date: Date
    let configuration: ConfigurationIntent
    let Obj1: Model
    let Obj2: Model
    let Obj3: Model
}

TimelineProvider -> IntentTimelineProvider

struct Provider: TimelineProvider {
    //设置默认视图
    func placeholder(in context: Context) -> SimpleEntry {
        simpleModel(Date(), config: ConfigurationIntent())
    }
    //小部件库中显示小部件，设置快照
    func getSnapshot(for configuration: ConfigurationIntent, in context: Context, completion: @escaping (SimpleEntry) -> ()) {
        let entry = simpleModel(Date(), config: configuration)
        completion(entry)
    }
    
    //设置时间线
    func getTimeline(for configuration: ConfigurationIntent, in context: Context, completion: @escaping (Timeline) -> ()) {
        var entries: [SimpleEntry] = []
        
        let currentDate = Date()
        for hourOffset in 0 ..< 15 {
            //设置刷新策略
            let entryDate = Calendar.current.date(byAdding: .minute, value: hourOffset, to: currentDate)!
            entries.append(simpleModel(entryDate, config: configuration))
        }
        //重启时间线策略
        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    }
}

StaticConfiguration -> IntentConfiguration

var body: some WidgetConfiguration {
     IntentConfiguration(kind: kind, intent: ConfigurationIntent.self, provider: Provider()) { entry in
     YourWidgetEntryView(entry: entry)
    }
    .configurationDisplayName("YourWidget")
    .description("YourWidget description")
 }

显示

Text(entry.configuration.parameter == nil ? "没有值" : entry.configuration.parameter!)

五、优化及调试

1. 优化

在widget使用数据之前，App应已经准备数据。使用共享组group存储数据。
让App使用后台处理时间来更新widget数据。
选择最合适的刷新策略。
仅当小部件当前显示的信息更改时，才调用reloadtimelines。

2. 调试

在Xcode中调试时，WidgetKit不会施加刷新次数限制。要验证Widget的行为是否正确，需使用真机测试。