打造錶面服務

錶面是 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 權限。請前往 Wear OS 應用程式和手機應用程式資訊清單檔案，在 manifest 元素下方新增以下權限：

<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 中的三個抽象方法，如以下範例所示：

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 = // ...

}

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

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