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. 結果

獲取應用中的兩個數據，傳遞到錶盤插件中