Criar um serviço para mostradores de relógio

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Um mostrador do relógio é um serviço empacotado em um app para Wear OS. Quando o usuário seleciona uma opção disponível, o mostrador do relógio aparece e os métodos de callback de serviço são invocados.

Quando o usuário instala um app para Wear OS que possui mostradores de relógio, eles ficam disponíveis no seletor do relógio. Opcionalmente, o usuário pode selecionar um mostrador de relógio de um app complementar no smartphone pareado.

Esta página descreve como configurar um projeto do Wear OS para incluir mostradores de relógio e como implementar um serviço de mostrador do relógio.

Criar um projeto de mostrador do relógio

Observação: recomendamos o uso do Android Studio para o desenvolvimento para Wear OS, porque ele oferece configuração de projetos, inclusão de bibliotecas e facilidades no empacotamento.

Conclua as etapas abaixo para criar um projeto no Android Studio para o mostrador do relógio:

  1. Clique em Studio > New > New project.
  2. Na janela Select a project template, selecione a guia Wear. Em seguida, selecione Watch Face na lista de opções e clique em Next.
  3. Na janela Configure your project, aceite os valores padrão e clique em Finish.

O Android Studio cria um projeto com um módulo app para o serviço de mostrador do relógio.

Dependências

O Android Studio adiciona automaticamente as entradas necessárias nos arquivos build.gradle. A biblioteca de mostradores de relógio AndroidX está incluída nas dependências. Consulte o exemplo de código no GitHub para conferir detalhes sobre essa biblioteca.

Referência da API da Biblioteca de Suporte Wearable

A documentação de referência traz informações detalhadas sobre as classes que você usa para implementar mostradores de relógio. Navegue pela documentação de referência da API da Biblioteca de Suporte para Wearables.

Declarar permissões

O mostrador do relógio requer a permissão WAKE_LOCK. Adicione a permissão abaixo aos arquivos de manifesto do app para Wear OS e do app para smartphones no elemento 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>

Suporte a dispositivos retangulares

Por padrão, os mostradores de relógio em dispositivos retangulares são executados no modo de emulação quadrada. Assim, há suporte a mostradores de relógio criados para dispositivos circulares e quadrados. Se você quiser oferecer suporte total a dispositivos retangulares, substitua esse comportamento criando uma tag meta-data no service do mostrador do relógio do seu manifest e definindo android.service.wallpaper.square_mode como false, conforme mostrado neste exemplo de código:

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

Implementar o serviço e os métodos de callback

Os mostradores de relógio no Wear OS são implementados como WatchFaceService. Para implementar um WatchFaceService, é necessário criar três objetos: um UserStyleSchema, um ComplicationSlotsManager e um WatchFace.

Esses três objetos são especificados substituindo três métodos abstratos do WatchFaceService, mostrados no exemplo a seguir:

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

}

Registrar o serviço de mostrador do relógio

Depois de implementar o serviço de mostrador do relógio, registre a implementação no arquivo de manifesto do app para wearables. Quando os usuários instalam esse app, o sistema usa as informações sobre o serviço para disponibilizar o mostrador do relógio no app complementar do Wear OS e no seletor de mostradores no dispositivo wearable.

O snippet abaixo mostra como registrar uma implementação de mostrador do relógio no elemento <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>

O app complementar do Wear OS by Google e o seletor de mostradores de relógio no wearable usam a imagem da prévia definida pela entrada de metadados com.google.android.wearable.watchface.preview ao apresentar aos usuários todos os mostradores de relógio instalados no dispositivo. Para gerar esse drawable, execute o mostrador do relógio no dispositivo Wear OS ou em uma instância do emulador e faça uma captura de tela. Em dispositivos Wear OS com telas hdpi, a imagem de visualização normalmente tem 320 x 320 pixels.

Os mostradores de relógio que têm aparência significativamente diferente em dispositivos redondos podem oferecer tanto imagens para visualizações redondas quanto quadradas. Para especificar uma imagem de visualização redonda, use a entrada de metadados com.google.android.wearable.watchface.preview_circular. Se o mostrador do relógio incluir ambas as imagens de visualização, o app complementar e o seletor de mostradores de relógio no wearable vão mostrar a opção adequada, de acordo com o formato do relógio. Se uma imagem de visualização redonda não for incluída, a imagem quadrada vai ser usada para dispositivos quadrados e redondos. Nos dispositivos redondos, uma imagem de visualização quadrada é cortada com uma forma circular.

A entrada de metadados android.service.wallpaper especifica o arquivo de recursos watch_face.xml, que contém um elemento wallpaper, conforme mostrado neste exemplo:

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

Seu app para wearables pode conter mais de um mostrador de relógio. É necessário adicionar uma entrada de serviço ao arquivo de manifesto do app para wearable para cada implementação de mostrador do relógio.

Confira os seguintes recursos relacionados: