設定錶面格式

注意：本頁面說明手動管理錶面設定的程序步驟。如果您想使用 WYSIWYG (所見即所得) 樣式的工具設計錶面，請先參閱 Watch Face Studio 指南。

本指南除了介紹以錶面格式設定錶面所需的工具，以及這些工具的使用步驟外，也針對專案架構提供了一些建議，包括逐步講解如何將工具應用於建立這個架構。

開始使用 Android Studio

如要手動開發錶面，最簡單的方法是使用 Android Studio。錶面支援功能適用於 Canary 版。

  1. 依序點選「File」>「New Project」。
  2. 在「Wear OS」下方，選取「基本錶面」

這會建立完整運作的錶面所需結構。

專案架構

當您使用錶面格式建立自訂錶面時，必須將包含自訂錶面檔案的 Android App Bundle 與包含 Wear OS 應用程式邏輯的 Android App Bundle 完全區隔開來。部分應用程式商店 (包括 Google Play) 會禁止上傳同時包含 Wear OS 邏輯和自訂錶面的 Android App Bundle。

宣告錶面格式版本

在新應用程式的資訊清單檔案 (AndroidManifest.xml) 中，檢查應用程式屬性，確認使用的是錶面格式。

錶面格式的部分功能僅適用於後續版本。請將這個屬性設為支援所需功能的最低值，盡可能提高裝置相容性，並將 minSdkVersion 設為相符值。進一步瞭解如何設定應用程式的版本。

<manifest ...>
    <!--
        Use SDK version 33 to support Watch Face Format (WFF) version 1 and
        higher, SDK version 34 to support WFF version 2 and higher, and so on.
    -->
    <uses-sdk
        android:minSdkVersion="34"
        android:targetSdkVersion="34" />

    <!--
        WFF is a resource-only format, so the hasCode attribute should be set to
        false to reflect this.
    -->
    <application
        android:label="@string/watch_face_name"
        android:hasCode="false"
        ...>
        <meta-data android:name="com.google.android.wearable.standalone"
            android:value="true" />
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="2" />
    </application>
</manifest>

宣告錶面中繼資料

在應用程式的 res/xml 資源目錄中，有名為 watch_face_info.xml 的檔案。您可以在這個檔案中定義錶面中繼資料：

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>

    <Preview value="@drawable/watch_face_preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
</WatchFaceInfo>

這個檔案中的欄位代表下列詳細資料：

Preview
用於參考內含錶面預覽圖片的可繪項目。
Category

用於定義錶面類別。必須是字串或字串的參照，例如 @string/ref_name。每個裝置製造商都可以定義自己的錶面類別組合。

預設值為 empty_category_meta，可將這個錶面與錶面挑選器檢視畫面底部的其他「empty category」錶面分為同一組。

AvailableInRetail

用於指出可否在裝置處於零售商展示模式時使用錶面。這必須是布林值，或是布林值的參照，例如 @bool/watch_face_available_in_retail。

預設值為 false。

MultipleInstancesAllowed

用於指出錶面是否可有多項常用工具。這必須是布林值，或是布林值的參照，例如 @bool/watch_face_multiple_instances_allowed。

預設值為 false。

Editable

用於指出錶面是否「可編輯」，可編輯的意思是錶面具有一項設定，或至少一個未固定的小工具。此屬性可用於在常用工具清單中顯示或隱藏錶面的「Edit」按鈕。

預設值為 false。

宣告錶面名稱

在應用程式的資訊清單檔案 (AndroidManifest.xml) 中，將 android:label 屬性設為錶面名稱：

<application android:label="@string/watch_face_name" >

宣告錶面詳細資料

基本 WFF 錶面文件的結構如下：

<WatchFace width="450" height="450">
  <Scene>
    <!-- Content to be rendered -->
  </Scene>
</WatchFace>

Android Studio 範本會在 res/raw/watchface.xml 中提供基本文件。如要支援不同螢幕形狀和大小，請宣告支援多種形狀和大小。

根元素一律為 WatchFace。height 和 width 會定義錶面使用的座標空間範圍，且錶面會縮放以配合所用裝置；height 和 width 不代表實際像素。

錶面格式會整理錶面的幾項詳細資料：

  • 中繼資料，例如錶面預覽圖片中顯示的時間和步數。
  • 使用者設定，例如錶面的不同色彩主題、使用者可切換的元素，以及多種元素可供選擇。錶面格式第 2 版導入了變體，可顯示在使用者設定中。每種風格都會指定預設使用者設定，包括錶面時間顯示的元素類型和樣式。這些預設設定可讓您輕鬆建立賞心悅目的元素群組。在 Wear OS 隨附應用程式中，使用者會在可捲動的列中看到錶面的不同風格。
  • 包含錶面視覺元素的場景。越接近場景結尾的元素會顯示在其他元素上方，因此一般順序如下：
    • 類比時鐘的指針或數位時鐘的文字
    • 顯示其他資訊的小工具，例如星期幾或使用者的步數
    • 其他可提供視覺趣味或裝飾錶面的圖像，例如露營地圖片
  • 元素群組：可同時修改多個元素。您可以在場景中建立這些群組的變體，以便在系統進入省電微光模式時，選擇性地隱藏或修改內容。

屬性皆屬於強型別，且設有頻率和有效值的規範，可在製作錶面時避免大部分的錯誤來源。

宣告支援的錶面形狀 (選用)

只有在想為不同大小的錶面提供不同行為時，才需要執行這個步驟。如果希望錶面隨著手錶大小縮放，可以略過這個步驟。

在應用程式的 res/xml 資源目錄中，於 watch_face_shapes.xml 宣告支援的錶面形狀組合：

<WatchFaces>
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
<WatchFaces>

接著，為每個錶面形狀定義錶面外觀和行為。如果沒有定義形狀檔案，則只需要一個檔案 watchface.xml。

以本節的範例來說，原始 XML 檔案會像這樣：

  • res/raw/watchface.xml
  • res/raw/watchface_large_circle.xml

識別錶面發布商 (選用)

您可以選擇在應用程式的資訊清單檔案中宣告任意字串，此字串可用於識別錶面的發布商，或您目前所用的工具名稱和版本：

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="<var>{toolName}-{toolVersion}</var>" />
</application>

檢查錶面是否正確且效能良好

在開發期間，以及上傳至 Google Play 之前，請使用 Android Studio 內建的錶面格式驗證功能，檢查錶面是否沒有語法錯誤。這項功能會自動醒目顯示程式碼中的錯誤，並支援版本。

您也應執行記憶體用量工具，確認錶面符合記憶體用量規定。

  • 如要瞭解如何為發布做好準備，請參閱這篇文章，進一步瞭解如何最佳化記憶體用量，以及這篇文章，瞭解如何檢查記憶體用量。
  • 進一步瞭解如何在開發週期中使用 XML 驗證工具。

建構錶面應用程式套件

如要建構及部署錶面，最簡單的方法是使用 Android Studio，因為這款工具內建支援錶面執行設定。按一下「Run」按鈕後，Android Studio 會將錶面部署至裝置或模擬器，並設為啟用中的錶面。

錶面範例

如需更多錶面格式專案範例，請參閱 GitHub。