打造錶面服務

錶面是 Wear OS 應用程式內隨附的服務。當使用者選取某個可用錶面後，系統便會顯示該錶面並叫用服務回呼方法。

如果使用者安裝了含有錶面的 Wear 應用程式，便可透過錶面選取器在手錶上使用這些錶面。另外，使用者也可以在配對的手機上透過隨附應用程式選取錶面。

本頁面將說明如何設定 Wear OS 專案，以便納入錶面，以及如何實作錶面服務。

建立錶面專案

注意：建議您使用 Android Studio 開發 Wear OS 應用程式，因為這項工具可以用來設定專案、加入程式庫，而且提供包裝的便利方式。

如要在 Android Studio 中為錶面建立專案，請按照下列步驟操作：

  1. 依序點選「File」>「New」>「New Project」。
  2. 在「Select a project template」視窗中選取「Wear」分頁標籤，然後從選項清單中選取「Watch Face」，再按一下「Next」。
  3. 在「Configure your project」視窗中接受預設值，然後按一下「Finish」。

Android Studio 會為錶面服務建立具有 app 模組的專案。

依附元件

Android Studio 會自動把必要的依附元件加入 build.gradle 檔案。依附元件包含 AndroidX 錶面程式庫；如要進一步瞭解這個程式庫，請參閱 GitHub 上的程式碼範例。

穿戴式裝置支援資料庫 API 參考資料

參考資料說明文件提供可用來實作錶面的類別詳細資訊。請參閱 API 參考資料說明文件，瞭解穿戴式裝置支援資料庫。

宣告權限

錶面必須使用 WAKE_LOCK 權限。在 manifest 元素下方，將以下權限新增至 Wear OS 應用程式和手機應用程式的資訊清單檔案：

<manifest ...>
    <uses-permission
        android:name="android.permission.WAKE_LOCK" />

    <!-- Required for complications to receive complication data and open the provider chooser. -->
    <uses-permission
        android:name="com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA"/>
    ...
</manifest>

支援直接啟動

您必須按照直接啟動指南操作，在「使用者解鎖」前提供錶面：

  1. 針對資訊清單中的服務，將 android:directBootAware 屬性設為 true。
  2. 錶面應將資訊儲存在 裝置加密儲存空間中。

實作服務和回呼方法

Wear OS 內的錶面會實作為 WatchFaceService。實作 WatchFaceService 需要建立三個物件：UserStyleSchema、ComplicationSlotsManager 和 WatchFace。

這三個物件的指定方式是覆寫 WatchFaceService 中的三個抽象方法，如以下範例所示：

Kotlin

class CustomWatchFaceService : WatchFaceService() {

    /**
     * The specification of settings the watch face supports.
     * This is similar to a database schema.
     */
    override fun createUserStyleSchema(): UserStyleSchema = // ...

    /**
     * The complication slot configuration for the watchface.
     */
    override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager = // ...

    /**
     * The watch face itself, which includes the renderer for drawing.
     */
    override suspend fun createWatchFace(
        surfaceHolder: SurfaceHolder,
        watchState: WatchState,
        complicationSlotsManager: ComplicationSlotsManager,
        currentUserStyleRepository: CurrentUserStyleRepository
    ): WatchFace = // ...

}

註冊錶面服務

實作錶面服務後，請在穿戴式應用程式的資訊清單檔案中註冊實作內容。當使用者安裝此應用程式後，系統便會使用本服務的資訊在 Wear OS 隨附應用程式和穿戴式裝置的錶面挑選工具中提供此錶面。

以下範例說明如何在 <application> 元素下方註冊錶面實作內容：

<service
    android:name=".AnalogWatchFaceService"
    android:label="@string/analog_name"
    android:permission="android.permission.BIND_WALLPAPER" >
    <meta-data
        android:name="android.service.wallpaper"
        android:resource="@xml/watch_face" />
    <meta-data
        android:name="com.google.android.wearable.watchface.preview_circular"
        android:resource="@drawable/preview_analog_circular" />
    <intent-filter>
        <action android:name="android.service.wallpaper.WallpaperService" />
        <category
            android:name=
            "com.google.android.wearable.watchface.category.WATCH_FACE" />
    </intent-filter>
</service>

當系統向使用者展示裝置內安裝的所有錶面時，Wear OS by Google 隨附應用程式和穿戴式裝置的錶面挑選工具都會使用 com.google.android.wearable.watchface.preview_circular 中繼資料項目定義的預覽圖片。如果要取得這個可繪項目，請在 Wear OS 裝置或模擬器執行個體中執行錶面，然後擷取螢幕截圖。在配備 HDPI 螢幕的 Wear 裝置上，預覽圖片大小通常為 320x320 像素。

android.service.wallpaper 中繼資料項目會指定 watch_face.xml 資源檔案，其中含有 wallpaper 元素，如以下範例所示：

<?xml version="1.0" encoding="UTF-8"?>
<wallpaper xmlns:android="http://schemas.android.com/apk/res/android" />

穿戴式應用程式內可以附有多種錶面。每個錶面實作都必須在穿戴式應用程式的資訊清單檔案中新增一個服務項目。

請參閱下列相關資源：