設定錶面格式

注意：本頁面將說明手動管理錶面設定的程序步驟。如果您想改用 WYSIWYG (What You See Is What You Get) 樣式工具設計錶面，請先參閱 Watch Face Studio 指南。

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

必要條件

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

  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 版。進一步瞭解如何設定應用程式的版本。

<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"
        ...>
        <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>

如果您使用單一錶面，請在建構錶面時將這個 XML 檔案設為 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"/>

    <!-- Remove any references to rectangular watch faces -->
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

接著，為每個錶面形狀定義錶面外觀和行為。如果您未定義形狀檔案，則只需建立一個 watchface.xml 檔案即可。

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

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

識別錶面發布商 (選用)

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

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

檢查錶面的正確性和效能

在開發期間，請在上傳至 Google Play 前使用驗證工具，確認錶面沒有錯誤，且符合記憶體使用量建議。

建構錶面應用程式套件

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

如需瞭解相關操作，請參閱 GitHub 範例。