在錶面新增小工具

錶面小工具可顯示資料來源的資料。您可以使用錶面格式選擇要取得基礎資料的資料來源。這樣一來，錶面不但可以顯示時間，還能顯示其他資訊，而且不需程式碼即可取得資料。

使用錶面格式

您可以使用 Complication 元素在單一錶面定義最多八個小工具。您也可以使用這個元素定義每個小工具在錶面上的顯示位置。

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

類型和欄位

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





類型 必填欄位 選填欄位 附註
SHORT_TEXT 簡短文字 圖示
影像烙印防護功能圖示
簡短名稱
內容說明

 如有提供圖示和/或簡短名稱，系統只會擇一顯示。
MONOCHROMATIC_IMAGE 單色圖片
 影像烙印防護功能圖示
內容說明

 在不需要文字時使用。圖示應使用單一顏色，並可由錶面調整色調。
RANGED_VALUE 值
最小值
最大值
 單色圖片
影像烙印防護功能圖示
簡短文字
簡短名稱
色彩漸層
動態值
內容說明

 如果您想自行繪製進度列，可以使用 isRangedValueProgressHidden() 方法隱藏 ComplicationDrawable 類別提供的進度列。
GOAL_PROGRESS 值
目標值
 單色圖片
影像烙印防護功能圖示
簡短文字
簡短名稱
色彩漸層
動態值
內容說明

 GOAL_PROGRESS 是用於從零開始計算且可超過目標值的項目，例如步數。
LONG_TEXT 詳細文字
 詳細名稱
單色圖片
影像烙印防護功能圖示
小型圖片
內容說明
 如有提供，就會顯示詳細名稱。
SMALL_IMAGE 小型圖片
 內容說明
 小型圖片有兩種樣式：相片樣式或圖示樣式。相片樣式表示圖片應該可以填充畫面空間且可裁剪。圖示樣式表示圖片無法裁剪，且可能會有邊框間距。由於圖片是可變的，若使用具備影像烙印防護功能或低位元微光模式的裝置，可能會顯示不適合在微光模式下顯示的圖片。啟用影像烙印防護功能或低位元微光模式時，錶面可能會使用影像烙印防護功能小型圖片，因為比較能安全顯示。否則，錶面會因難以判斷圖片是否合適，而不顯示圖片。
LARGE_IMAGE 大型圖片
 內容說明
 這類圖片應大到足以填滿整個錶面。由於圖片是可變的，若使用具備影像烙印防護功能或低位元微光模式的裝置，可能會顯示不適合在微光模式下顯示的圖片。錶面很難判斷圖片是否適合顯示，因此如果已啟用影像烙印防護功能或低位元微光模式，錶面就不會在微光模式下顯示圖片。
WEIGHTED_ELEMENTS 元素清單
 單色圖片
影像烙印防護功能圖示
簡短文字
簡短名稱
內容說明
 每個元素都包含色彩和權重 (大於零)。元素算繪後的大小應與權重成正比。權重不需要加總至任何特定值。請注意，錶面可以為 WEIGHTED_ELEMENTS 變更顏色。

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

  • 未選取來源
  • 使用者已為版位選取「空白」
  • 來源沒有任何資料可傳送

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

小工具類型 說明
TYPE_NOT_CONFIGURED 如果小工具已啟用，但使用者未選取來源且未設定預設值，系統會傳送此類型。

無法由來源傳送。
TYPE_EMPTY 使用者已啟用小工具，但選取「空白」而非來源，或是錶面未選擇來源，而此小工具類型為預設值時，系統會傳送此類型。

無法由來源傳送。
TYPE_NO_DATA 使用者啟用具有來源的小工具後，系統會傳送此類型，從來源收到實際資料前先清除小工具。

如果來源沒有實際資料可傳送，則可由來源傳送該類型。

在某些裝置上，錶面和小工具必須使用錶面格式

如果您現有的錶面使用 Jetpack 錶面程式庫或 穿戴式裝置支援資料庫，使用者仍可在下列裝置的錶面小工具中看到所有資料來源的資料：

  • 搭載 Wear OS 4 以下版本的裝置。
  • 已收到 OTA 升級至 Wear OS 5 的裝置。

此外，如果您現有的錶面使用 Jetpack Watch Face 程式庫或穿戴式裝置支援資料庫，且已安裝在上述其中一部裝置上，錶面就能繼續接收更新。

不過，在搭載 Wear OS 5 的新款智慧手錶上，錶面必須符合錶面格式。因此，建議您改用錶面格式。