錶面小工具可以顯示來自資料來源的資料。錶面可以藉由使用 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 範例。