打造錶面服務

錶面是 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 需要建立三個物件:UserStyleSchemaComplicationSlotsManagerWatchFace

這三個物件的指定方式是覆寫 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 裝置上,預覽圖片大小通常為 320 x 320 像素。

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

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

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

請參閱下列相關資源: