在錶面新增小工具

Stay organized with collections Save and categorize content based on your preferences.

錶面小工具可以顯示來自資料來源的資料。錶面可以藉由使用 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 簡短文字 圖示
影像烙印防護功能圖示
簡短名稱
如果提供一或兩個項目,則只會顯示一個圖示或簡短名稱。
圖示 圖示 影像烙印防護功能圖示 在不需要使用文字時使用。圖示應使用單一顏色,並可由錶面調整色調。
RANGED_VALUE
最小值
最大值
圖示
影像烙印防護功能圖示
簡短文字
簡短名稱
系統不保證能夠顯示選填欄位。如果您想自行繪製進度列,可以使用 isRangedValueProgressHidden() 方法隱藏 ComplicationDrawable 類別提供的進度列。
LONG_TEXT 詳細文字 詳細名稱
圖示
影像烙印防護功能圖示
小型圖片
顯示詳細名稱 (如有)。
SMALL_IMAGE 小型圖片 小型圖片有兩種樣式:相片樣式圖示樣式。相片樣式代表應該會填滿整個空間,並可以進行裁剪;圖示樣式則代表不應裁剪,且可以加上邊框間距。如果裝置設有影像烙印防護功能或備有低位元率微光模式,則圖像變數可能會導致圖像不適合在微光模式下顯示。如果使用者啟用了影像烙印防護功能或低位元率微光模式,錶面可以安全使用 Burn-in protection small image。否則,由於錶面很難判斷適不適合使用圖像,因此不應顯示圖像。
LARGE_IMAGE 大型圖片 這類圖像應該夠大,足以填滿整個錶面。如果裝置設有影像烙印防護功能或備有低位元率微光模式,則圖像變數可能會導致圖像不適合在微光模式下顯示。由於錶面很難判斷適不適合顯示圖像,因此在使用者啟用影像烙印防護功能或低位元率微光模式時,錶面不應在微光模式下顯示圖像。

下表內的類型是空白資料,可以傳送到任何小工具版位。這些類型內並無欄位,不需要列在支援類型清單中。這些類型可以讓錶面分辨以下三種用途:

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

來源不應為了回應更新要求而傳送 TYPE_EMPTY,而應該傳送 TYPE_NO_DATA

「空白」資料的小工具類型詳情請見下表:

小工具類型 說明
TYPE_NOT_CONFIGURED 系統會在使用者啟用小工具,但並未指定來源和設定預設值時傳送此項目。

無法由來源傳送。

TYPE_EMPTY 系統會在使用者啟用小工具,且並未指定來源而選擇「空白」時,或是當錶面未指定來源而此小工具類型為預設時傳送此項目。

無法由來源傳送。

TYPE_NO_DATA 系統會在使用者啟用 (有來源的) 小工具時傳送此項目,以便在實際收到來源的資料前清除小工具。

如果來源沒有實際可傳送的資料,則應由來源傳送。

詳情請參閱 GitHub 上的 WatchFace 範例