swift Apple Watch App 如何添加 Complication

swift Apple Watch App 如何添加 Complication

建议每一个 Apple Watch 应用都实现 Complication， Complication 就是能显示在表盘上的一些应用组件，实现 Complication 以后系统会给予一些优先的权限，好比后台任务刷新：在没有实现 Complication 的时候系统1小时只会分配一次后台刷新，实现以后会实现屡次。

添加 Complication 的官方说明: https://developer.apple.com/documentation/clockkit/adding_a_complication_to_your_watchos_app

当你在新建项目的时候没有勾选 complication 这一项，在后来又如何添加呢？

1. 新建一个实现了 CLKComplicationDataSource 的类

点击 fix 系统会自动添加这个 protocal 中必需的方法和变量。

2. 配置 complication

点击总项目，选择 target 为 extension， 如图

再切到 general 标签，就会看到对应的 complication 的相关设置了

3. 实现代码

显示在表盘的 complication 须要经过实现 CLKComplicationDataSource 接口的类获取它须要的数据。

必须实现 CLKComplicationDataSource 中的两个方法，
一个是用于定义 complication 可获取的数据方向 getSupportedTimeTravelDirections
一个是给 complication 实时显示提供数据

注意： 由于 complication 显示是实时的，因此不要在提供数据的方法里写过量计算、须要大量时间运行的代码，若是须要显示一些大量计算的数据，必定要事先把数据处理好并存在一个地方，在用的时候直接取就能够了，不耗费时间。

还有其它一些可选的方法，具体能够查看 --> CLKComplicationDataSource 的 API <--
如，

// 提供时间轴中将来数据样本的方法：
func getTimelineEntries(for complication: CLKComplication, before date: Date, limit: Int, withHandler handler: @escaping ([CLKComplicationTimelineEntry]?) -> Void)
// 提供时间轴中过去数据样本的方法：
func getTimelineEntries(for complication: CLKComplication, after date: Date, limit: Int, withHandler handler: @escaping ([CLKComplicationTimelineEntry]?) -> Void)

4. 具体实现代码

好比个人

1） 定义 complication 可向 [前,后] 两个方向获取数据

func getSupportedTimeTravelDirections(for complication: CLKComplication, withHandler handler: @escaping (CLKComplicationTimeTravelDirections) -> Void) {
    handler([.forward, .backward])
}

2) 给实时显示在表盘的 complication 提供显示的数据

这里须要说明一下：
a. 关于表盘插件的样式
全部可能表盘插件样式都在 CLKComplicationFamily 里列出来了，能够查看 CLKComplicationFamily 官方文档了解

b. 关于实现表盘数据的类
全部 template 样板都是从虚拟类 CLKComplicationTemplate 继承过来的，包括各类表盘插件所用的样式类，根据本身须要进行操做，以下图，都是：

func getCurrentTimelineEntry(for complication: CLKComplication, withHandler handler: @escaping (CLKComplicationTimelineEntry?) -> Void) {
    var startLevel = 0
    var timeDistance = 0.0
    if let timeStart = defaults.object(forKey: Const.timeStart) as? Date {
        startLevel = Int(defaults.double(forKey: Const.startLevel) * 100)
        timeDistance = Date().distance(to: timeStart)
    }
    switch complication.family {
    
    // 这里，对应不一样的 family，也就是表盘中的插件样式的不一样，须要返回对应样式的 template。
    case .graphicCircular:
        let template = CLKComplicationTemplateGraphicCircularStackText()
        template.line1TextProvider = CLKSimpleTextProvider(text: "\(startLevel)")
        template.line2TextProvider = CLKSimpleTextProvider(text: timeDistance.timeFormatString)
        let entry = CLKComplicationTimelineEntry(date: Date(), complicationTemplate: template)
        handler(entry)
    case .graphicCorner:
        // 不一样 template 有不一样的实现类
        let template = CLKComplicationTemplateGraphicCornerStackText()
        template.innerTextProvider = CLKSimpleTextProvider(text: "\(startLevel)")
        template.outerTextProvider = CLKSimpleTextProvider(text: timeDistance.timeFormatString)
        let entry = CLKComplicationTimelineEntry(date: Date(), complicationTemplate: template)
        handler(entry)
    case .graphicBezel:
        let circle = CLKComplicationTemplateGraphicCircular()
        circle.tintColor = Colors.magenta
        let template = CLKComplicationTemplateGraphicBezelCircularText()
        template.circularTemplate = circle
        template.textProvider = CLKSimpleTextProvider(text: timeDistance.timeFormatString)
        let entry = CLKComplicationTimelineEntry(date: Date(), complicationTemplate: template)
        handler(entry)
    default:
        handler(nil)
    }
}

5. 结果

获取应用中的两个数据，传递到表盘插件中