設定錶面格式

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

必要條件

為了讓開發環境做好使用錶面格式的準備，請完成下列設定步驟：

  1. 安裝適用於 Android 14 (API 級別 34) 以上版本的 SDK。如果錶面不依賴特定於第 2 版的功能或行為，您可以改為安裝 Android 13 (API 級別 33) 的 SDK。

    這個 SDK 包含其他必要工具，包括 aapt2 和 android.jar。

  2. 或者，您也可以安裝 Android Studio，這款軟體也提供這些工具。

專案架構

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

建立錶面套件

如要建立含有錶面檔案的 Android App Bundle，請完成以下各節所列步驟。

宣告使用錶面格式

在新應用程式的資訊清單檔案 (AndroidManifest.xml) 中，加入應用程式屬性，指明使用的是錶面格式。除非您想限制搭載 Wear OS 5 以上版本的裝置存取錶面，否則請建立 2 個不同的錶面 APK，一個支援第 2 版，另一個支援第 1 版。進一步瞭解如何設定應用程式版本。

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest ...>
    <!--
        Use SDK version 34 for version 2 of WFF, and SDK version 33 for version
        1 of WFF
    -->
    <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"
        ...>
        <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>
    <!-- Only "Preview" is required. -->
    <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" >

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

只有在您想支援不同大小的錶面時，才需要執行這個步驟。如果您希望錶面可隨著手錶大小調整，可以略過這個步驟。

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

<WatchFaces>
    <!-- The default shape is "CIRCLE". -->
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

宣告錶面詳細資料

依據您在宣告支援的錶面形狀時使用的 file 屬性值，在應用程式的 res/raw 資源目錄中建立相對應的檔案。

您可以在這個檔案中，為每個錶面形狀定義錶面外觀和行為。如果沒有定義形狀檔案，則只需要建立一個檔案 watchface.xml。

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

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

根元素一律為 WatchFace：

<WatchFace width="450" height="450" clipShape="CIRCLE">
    <!-- Remainder of your Watch Face Format definition here. -->
    <!-- If this file defines a watch face for a circular device shape, place
         resources used in this file in the "/res/drawable-nodpi" directory. -->
    <!-- If this file defines a watch face for a rectangular or other
         non-circular shape, place resources ued in this file in the
         "/res/drawable-notround-nodpi" directory. -->
</WatchFace>

識別錶面發布商 (選用)

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

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

檢查錶面的正確性和效能

在開發期間和上傳至 Google Play 前，請使用驗證工具檢查錶面是否正確無誤，且符合記憶體用量建議。

建構錶面應用程式套件

如要建構包含錶面的 Android App Bundle，請使用 Gradle 建構系統。進一步瞭解如何使用 Gradle 建構應用程式。

這項說明在 GitHub 範例中說明。