打造錶面服務

錶面是一種 Wear OS 應用程式內封裝的服務。當使用者選取某個可以使用的錶面後,手錶便會顯示該錶面並叫用服務回呼方法。

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

本頁面將說明如何設定 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 參考文件瞭解穿戴式裝置支援資料庫。

注意:我們建議使用 Android Studio 開發 Wear OS 應用程式,因為這項工具可以用來設定專案,而且內附程式庫和套件,非常便利。

宣告權限

錶面必須使用 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>

支援矩形裝置

矩形裝置的錶面會預設使用方形模擬模式,以便支援為圓形和方形裝置設計的錶面。如果您希望完整支援矩形裝置,請在 manifest 的錶面 service 內新增 meta-data 標記,然後將 android.service.wallpaper.square_mode 設為 false,如以下程式碼範例所示:

<manifest ...>
    <application ...>
        <service
            android:name=".MyWatchFace"
            android:label="My Watch Face"
            android:permission="android.permission.BIND_WALLPAPER">

            ...

            <meta-data
                android:name="android.service.wallpaper.square_mode"
                android:value="false" />
            ...
        </service>
    ...
    </application>
    ...
</manifest>

實作服務和回呼方法

Wear OS 內的錶面會實作為 WatchFaceService。實作 WatchFaceService 必須建立三個物件:UserStyleSchemaComplicationSlotsManagerWatchFace

您可以覆寫 3 種來自 WatchFaceService 的抽象方法,便可指定這 3 種物件:

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"
        android:resource="@drawable/preview_analog" />
    <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 中繼資料項目定義的預覽圖片。如果要取得這個可繪項目,請在您的 Wear OS 裝置或模擬器執行個體中執行錶面,然後擷取螢幕截圖。在使用 HDPI 螢幕的 Wear 裝置上,預覽圖片大小通常為 320x320 像素。

如果錶面在圓形裝置上的外觀變化幅度很大,您可以提供圓形和方形的預覽圖片。請用 com.google.android.wearable.watchface.preview_circular 中繼資料項目指定圓形預覽圖片。如果錶面有提供兩種預覽圖片,隨附應用程式和穿戴式裝置的錶面挑選工具會按照手錶形狀顯示最合適的圖片。如果並未提供圓形預覽圖片,則方形和圓形裝置都會使用方形預覽圖片。在圓形裝置上,系統會用圓形裁剪方形的預覽圖片。

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

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

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

請參閱下列相關資源: