在錶面新增小工具

錶面小工具可以顯示來自資料來源的資料。錶面可以藉由使用 Complications API 選擇基礎資料的資料來源。如此一來，錶面不但可以顯示時間，還能顯示其他資訊，而且不需程式碼即可取得資料。

使用 ComplicationSlotsManager

如想將小工具加入錶面，請使用 ComplicationSlotsManager。

ComplicationSlotsManager 可定義錶面支援的小工具數量，以及小工具在螢幕上的位置。為了支援小工具變更位置和數量等資訊，ComplicationSlotsManager 也會使用 CurrentUserStyleRepository，如以下範例所示：

 override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager {
        val defaultCanvasComplicationFactory =
            CanvasComplicationFactory { watchState, listener ->
                // ...
            }

        val leftComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 100,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        val rightComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 101,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        return ComplicationSlotsManager(
            listOf(leftComplicationSlot, rightComplicationSlot),
            currentUserStyleRepository
        )
 }

類型和欄位

下表將說明 ComplicationData 物件的類型和欄位。當錶面請求小工具類型無效的欄位時，系統會回傳該欄位的預設值。舉例來說，如果錶面嘗試存取 SHORT_TEXT 類型內的 LONG_TEXT 欄位，系統便會回傳 LONG_TEXT 欄位的預設值：null。

類型	必填欄位	選填欄位	附註
`SHORT_TEXT`	簡短文字	圖示影像烙印防護功能圖示簡短名稱	如果提供一或兩個項目，則只會顯示一個圖示或簡短名稱。
`ICON`	圖示	影像烙印防護功能圖示	在不需要使用文字時使用。圖示應使用單一顏色，並可由錶面調整色調。
`RANGED_VALUE`	值最小值最大值	圖示影像烙印防護功能圖示簡短文字簡短名稱	系統不保證能夠顯示選填欄位。如果您想自行繪製進度列，可以使用 `isRangedValueProgressHidden()` 方法隱藏 `ComplicationDrawable` 類別提供的進度列。
`LONG_TEXT`	詳細文字	詳細名稱圖示影像烙印防護功能圖示小型圖片	顯示詳細名稱 (如有)。
`SMALL_IMAGE`	小型圖片		小型圖片有兩種樣式：相片樣式或圖示樣式。相片樣式表示圖片應該可以填充畫面空間且可裁剪。圖示樣式表示圖片無法裁剪，且可能會有邊框間距。由於圖片是可變的，若使用具備影像烙印防護功能或低位元微光模式的裝置，可能會顯示不適合在微光模式下顯示的圖片。啟用影像烙印防護功能或低位元微光模式時，錶面可能會使用「影像烙印防護小圖」，因為這類圖片十分安全。否則，由於錶面難以判斷圖片是否合適，因此不會顯示圖片。
`LARGE_IMAGE`	大型圖片		這類圖像應該夠大，足以填滿整個錶面。由於圖片是可變的，若使用具備影像烙印防護功能或低位元微光模式的裝置，可能會顯示不適合在微光模式下顯示的圖片。由於錶面很難判斷圖片是否適合顯示，因此若使用者啟用影像烙印防護功能或低位元率微光模式，錶面不會在微光模式下顯示圖片。

下表說明可對任何小工具版位傳送空白資料的小工具類型。這些類型不含任何欄位，也不必納入支援的類型清單中。這些類型可以讓錶面分辨以下三種情況：

未選取任何來源
使用者已為運算單元選取「空白」
來源沒有任何資料可傳送

來源不得傳送 TYPE_EMPTY 以回應更新要求，請改為傳送 TYPE_NO_DATA。

小工具類型	說明
`TYPE_NOT_CONFIGURED`	使用者已啟用小工具，但並未選取來源和設定預設值時，系統會傳送此類型。無法由來源傳送。
`TYPE_EMPTY`	使用者已啟用小工具，但選取「空白」而非來源，或是錶面未選擇來源，而此小工具類型為預設值時，系統會傳送此類型。無法由來源傳送。
`TYPE_NO_DATA`	使用者啟用具有來源的小工具後，系統會傳送此類型，以便在從來源收到實際資料之前先將小工具清除。如果來源沒有實際資料可傳送，則可由來源傳送該類型。

詳情請參閱 GitHub 上的 WatchFace 範例。