Como criar mostradores do relógio para o Wear OS

1. Antes de começar

Ao criar mostradores para o Wear OS, os desenvolvedores precisam usar o Formato do Mostrador do Relógio, um formato baseado em XML que permite criar mostradores expressivos e com bom desempenho.

Este codelab é destinado a pessoas que querem criar mostradores do relógio manualmente usando XML ou que querem entender melhor o formato para criar ferramentas de design próprias.

Se você quiser usar ferramentas gráficas para criar seu próprio mostrador do relógio, recomendamos que confira as ferramentas atuais, como o Watch Face Studio.

Pré-requisitos

Experiência com XML.

O que você vai fazer

Neste codelab, você vai aprender o seguinte:

Como os mostradores de relógio do Formato do Mostrador do Relógio são empacotados.
Como criar um mostrador do relógio, incluindo o modo ambiente.
Como adicionar elementos, como formas.
Como incorporar fontes de dados ao mostrador do relógio.
Como resolver problemas no mostrador do relógio.

Você vai criar um mostrador do relógio personalizável, com vários temas de cores, contagem de passos integrada e indicador de data.

O que é necessário

Android Studio Meerkat ou versões mais recentes: embora não seja necessário usar o Android Studio diretamente, essa é a maneira mais fácil de garantir que as ferramentas de build do Android e as ferramentas da plataforma estejam instaladas e serão usadas.
Um emulador do Wear OS ou um relógio Wear OS físico, com as opções para desenvolvedores ativadas.

2. Entender a estrutura do projeto do Formato do Mostrador do Relógio

Baixar os arquivos do codelab

Para começar, baixe os arquivos do codelab aqui

$ git clone https://github.com/android/codelab-watch-face-format

Se preferir, faça o download do repositório como um arquivo ZIP:

Há dois projetos no diretório watch-face-format: start e finish. Usaremos o projeto start, mas você pode conferir o projeto finish quando quiser, que contém o codelab concluído.

Vamos inspecionar a estrutura básica do projeto do Formato do Mostrador do Relógio. Você pode usar um editor da sua escolha ou abrir o projeto inicial no Android Studio usando File > Open… e selecionando o diretório start.

No diretório start/watchface/src/main, você vai encontrar os seguintes arquivos. Vamos ver o que cada um faz:

Arquivo	Descrição
`AndroidManifest.xml`	Assim como em um app Android comum, esse arquivo contém informações essenciais sobre o mostrador do relógio e o que é necessário para criá-lo.
`res/xml/watch_face_info.xml`	O arquivo de informações do mostrador do relógio contém metadados sobre ele, por exemplo, como encontrar a imagem de visualização e se o mostrador é personalizável.
`res/raw/watchface.xml`	Esse arquivo contém a definição do mostrador do relógio. Embora seja possível ter mais de uma definição, esse é o arquivo padrão usado.
`res/drawable/preview.png`	Cada mostrador do relógio precisa ter uma imagem de prévia usada pelo sistema. Para que esse projeto seja criado, a pasta "start/" contém uma prévia em branco. Vamos atualizá-la mais tarde.
`res/drawable/hour.pngres/drawable/minute.pngres/drawable/second.png`	Estes são os ponteiros do relógio que vamos usar no mostrador.
`res/values/strings.xml`	Assim como em um app Android, contém strings que podem ser usadas no mostrador do relógio.

Onde está o código?

Observe que não há código no projeto. Além do arquivo AndroidManifest.xml, todos os arquivos do projeto ficam em res/, o diretório de recursos. Isso ocorre porque os mostradores do Formato do Mostrador do Relógio não podem conter nenhum código: se você tentar incluir código Kotlin ou Java, por exemplo, ele não será aceito pela Play Store.

O sistema Wear OS lê esses recursos e cuida da criação e execução do mostrador do relógio para você. Assim, não é necessário nenhum tempo de execução ou outra lógica, o que economiza seu esforço de desenvolvimento.

3. Como criar um mostrador do relógio

Vamos atualizar cada um dos arquivos acima para criar um mostrador do relógio funcional.

Como preparar o manifesto

Para identificar o pacote como um Formato do Mostrador do Relógio, o manifesto precisa declarar duas coisas:

Não há código no projeto.
A versão do Formato do Mostrador do Relógio em uso.

Primeiro, atualize o elemento <application> para adicionar o atributo hasCode:

<application
    android:label="@string/watch_face_name"
    android:hasCode="false">

Em segundo lugar, adicione uma <property> ao elemento <application> especificando a versão do Formato do Mostrador do Relógio usada neste mostrador:

<property
    android:name="com.google.wear.watchface.format.version"
    android:value="1" />

Como definir o arquivo `watch_face_info`

O arquivo watch_face_info.xml tem um requisito obrigatório: especificar o local da imagem de prévia. Neste projeto, fornecemos uma imagem de prévia em res/drawable/preview.png. Este é um arquivo em branco, mas vamos atualizá-lo mais tarde com uma captura de tela real do mostrador do relógio finalizado.

Como parte do codelab, também vamos personalizar o mostrador do relógio. Também declaramos isso no watch_face_info.xml file usando o elemento <Editable>.

Atualize o arquivo res/xml/watch_face_info.xml para adicionar os seguintes elementos:

<Preview value="@drawable/preview" />
<Editable value="true" />

Como gravar o Formato do mostrador do relógio em XML

A definição do mostrador do relógio real está contida em res/raw/watchface.xml. Inspecione esse arquivo no editor. O elemento <WatchFace> define uma largura e uma altura de 450 por 450 para o mostrador do relógio. Esse espaço de coordenadas é usado no restante do arquivo, independente das dimensões reais de pixels em que o mostrador do relógio é executado, aumentando ou diminuindo o tamanho.

O XML tem esta aparência:

<?xml version="1.0"?>
<WatchFace width="450" height="450">
  <Scene>
    <PartText x="0" y="0" width="450" height="450">
      <Text>
        <Font family="SYNC_TO_DEVICE" size="48">Hello, World!</Font>
      </Text>
    </PartText>
  </Scene>
</WatchFace>

Por enquanto, essa definição vai mostrar apenas "Hello, World!" no relógio, não as horas. Mas vamos voltar para corrigir isso. Vamos ver como criar e colocar o mostrador do relógio no dispositivo.

Como criar e implantar o mostrador do relógio

Na linha de comando, verifique se você está no diretório inicial e use o comando:

./gradlew installDebug

Ou no Windows:

gradlew.bat installDebug

Isso vai criar e instalar o mostrador do relógio no dispositivo. Toque e mantenha pressionada a tela do mostrador do relógio e encontre o mostrador Codelab. Você também pode definir o mostrador do relógio na linha de comando usando:

adb shell am broadcast -a com.google.android.wearable.app.DEBUG_SURFACE --es operation set-watchface --es watchFaceId com.example.codelab

Agora, você verá o mostrador do relógio no relógio ou no emulador. Parabéns!

4. Como adicionar o horário

O Formato do Mostrador do Relógio pode ser usado para relógios analógicos e digitais. Você pode até ter os dois ou vários em um único mostrador.

Vamos ver como adicionar um relógio analógico usando o elemento < AnalogClock>. Primeiro, remova todo o elemento < PartText> do arquivo watchface.xml e substitua pelo seguinte:

<AnalogClock x="0" y="0" width="450" height="450">
  <!-- TODO: Add shadows here later -->
  <HourHand resource="hour"
      x="215" y="50" width="20" height="190"
      pivotX="0.5" pivotY="0.921" >
  </HourHand>
  <MinuteHand resource="minute"
      x="217" y="25" width="16" height="220"
      pivotX="0.5" pivotY="0.9">
  </MinuteHand>
  <SecondHand resource="second"
      x="221" y="15" width="8" height="245"
      pivotX="0.5" pivotY="0.857">
    <Variant mode="AMBIENT" target="alpha" value="0" />
    <Sweep frequency="15" />
  </SecondHand>
</AnalogClock>

O elemento <AnalogClock> tem altura e largura de 450, ocupando toda a tela. Ele também tem três elementos filhos: < HourHand>, < MinuteHand> e < SecondHand>. Confira como eles são definidos:

Recurso: cada um desses elementos filhos tem um atributo de recurso, que corresponde a um recurso drawable. Por exemplo, há um arquivo hour.png em res/drawable, que é usado pelo elemento <HourHand>. Não é necessário especificar @drawable.
Pontos de rotação: os ponteiros são girados automaticamente, mas pivotX e pivotY especificam onde a rotação deve ocorrer. pivotY, por exemplo, é calculado desta forma:

Variante: o <SecondHand> inclui um elemento filho < Variant>. Isso oculta o ponteiro dos segundos, já que o mostrador do relógio só é atualizado a cada minuto quando está no modo ambiente.

Agora, execute o seguinte comando para recriar e implantar o mostrador do relógio no dispositivo ou emulador:

./gradlew installDebug

Desta vez, o relógio está funcionando, mas ainda há muito o que fazer para melhorar.

5. Como adicionar cores e temas

Parte do que torna os mostradores de relógio divertidos é que eles podem ser personalizados e expressivos.

Nosso mostrador do relógio branco está um pouco simples no momento, então vamos adicionar um pouco de cor. Além disso, vamos tornar os temas de cores personalizáveis.

Como criar o ColorConfiguration

Primeiro, vamos definir os temas de cores que estarão disponíveis no mostrador do relógio. No arquivo watchface.xml, encontre o texto  e substitua-o por:

<UserConfigurations>
  <ColorConfiguration id="themeColor" displayName="color_label" defaultValue="0">
    <ColorOption id="0" displayName="color_theme_0" colors="#ffbe0b #fb5607 #ff006e #8338ec #883c3c3c" />
    <ColorOption id="1" displayName="color_theme_1" colors="#8ecae6 #219ebc #ffb703 #fb8500 #883c3c3c" />
    <ColorOption id="2" displayName="color_theme_2" colors="#ff595e #ffca3a #8ac926 #1982c4 #883c3c3c" />
    <ColorOption id="3" displayName="color_theme_3" colors="#ff0000 #00ff00 #ff00ff #00ffff #883c3c3c" />
    <ColorOption id="4" displayName="color_theme_4" colors="#ff99c8 #fcf6bd #d0f4de #a9def9 #883c3c3c" />
    <ColorOption id="5" displayName="color_theme_5" colors="#1be7ff #6eeb83 #e4ff1a #ffb800 #883c3c3c" />
  </ColorConfiguration>
</UserConfigurations>

Isso define 6 temas de cores, cada um com 5 cores. Cada tema é uma lista de cores separada por espaços, como mostrado no atributo colors.

Cada tema precisa de um nome fácil de entender. Por isso, adicione as seguintes definições ao arquivo res/values/strings.xml:

<string name="color_label">Color Theme</string>
<string name="color_theme_0">Bold</string>
<string name="color_theme_1">Magic</string>
<string name="color_theme_2">Breeze</string>
<string name="color_theme_3">Daytime</string>
<string name="color_theme_4">Relaxed</string>
<string name="color_theme_5">Smart</string>

Como usar o ColorConfiguration

Depois de definir os temas de cores, aplique-os aos ponteiros do relógio adicionando um atributo tintColor a cada um deles. Modifique o arquivo watchface.xml desta forma:

<HourHand ... tintColor="[CONFIGURATION.themeColor.0]">
...
<MinuteHand ... tintColor="[CONFIGURATION.themeColor.1]">
...
<SecondHand ... tintColor="[CONFIGURATION.themeColor.2]">

O <HourHand> faz referência à primeira cor do tema selecionado, o <MinuteHand> à segunda cor e o <SecondHand> à terceira.

Recrie e implante o mostrador do relógio, como antes. Agora, ele está colorido.

Além disso, se você tocar e manter pressionado o mostrador do relógio e tocar no botão de configurações, poderá escolher entre os 6 temas de cores.

6. Como adicionar uma cor de plano de fundo

Há mais algumas coisas que podemos fazer para destacar esse mostrador do relógio. Vamos adicionar um plano de fundo em negrito. Embora o plano de fundo continue predominantemente preto, esse toque de cor vai ajudar a melhorar a aparência.

Vamos usar o elemento < PartDraw> do Formato do Mostrador do Relógio, que permite criar uma camada para desenhar primitivas, como linhas, retângulos, ovais e arcos. Substitua o texto  pelo seguinte:

<Group x="100" y="100" width="250" height="250" name="background" alpha="127">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <PartDraw x="0" y="0" width="250" height="250">
    <Ellipse x="0" y="0" width="250" height="250">
      <Fill color="[CONFIGURATION.themeColor.3]" />
    </Ellipse>
    <Ellipse x="50" y="50" width="150" height="150">
      <Fill color="#000000" />
    </Ellipse>
  </PartDraw>
</Group>

Observe o uso do elemento <Variant> de novo: isso vai remover o anel do plano de fundo no modo ambiente para minimizar o número de pixels iluminados.

Observe também como estamos usando o tema de cores de novo para selecionar a cor do anel, mantendo o estilo em todos os elementos do mostrador do relógio.

7. Como validar o mostrador do relógio

Antes de continuar a melhorar o mostrador do relógio, vamos explorar como agilizar o processo de desenvolvimento usando o validador do Formato do Mostrador do Relógio.

O validador é uma ferramenta que verifica se o XML está correto, o que impede a criação e implantação de um mostrador do relógio que não funciona.

Baixe o arquivo JAR do validador no repositório do GitHub (link em inglês).
Execute o validador no arquivo watchface.xml.

java -jar wff-validator.jar 1 watchface/src/main/res/raw/watchface.xml

Se o XML do mostrador do relógio for válido, você vai receber uma mensagem de confirmação. No entanto, se um erro for encontrado, os detalhes e o local dele serão mostrados. Por exemplo:

SEVERE: [Line 18:Column 49]: cvc-complex-type.2.4.a: Invalid content was found starting with element 'PartDrw'

8. Como usar fontes de dados

O Formato do Mostrador do Relógio pode usar várias fontes de dados diferentes para tornar o mostrador mais útil.

Vamos adicionar duas fontes de dados usadas com frequência que ajudam a dar mais utilidade ao mostrador do relógio: a data atual (quem nunca esqueceu que dia era?) e a contagem de passos diários.

Cada um desses elementos é colocado em um contêiner < PartText>, que é uma camada feita para realizar operações de texto.

Como adicionar a data

Substitua o texto  pelo seguinte:

<PartText x="225" y="225" width="225" height="225">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <TextCircular centerX="0" centerY="0" width="415" height="415" startAngle="180" endAngle="90" align="CENTER" direction="COUNTER_CLOCKWISE">
    <Font family="SYNC_TO_DEVICE" size="28" color="[CONFIGURATION.themeColor.0]">
      <Template>
        <![CDATA[%d %s]]>
        <Parameter expression="[DAY]"/>
        <Parameter expression="[MONTH_S]"/>
      </Template>
    </Font>
  </TextCircular>
</PartText>

No snippet acima, usamos < Template> para formatar duas fontes de dados em uma string. DAY é um número inteiro de 1 a 31, e MONTH_S já é uma string. Por isso, usamos a expressão de formatação %d %s para colocar o número inteiro e a string juntos.

Envolver isso com um elemento CDATA é uma boa prática, já que evita que espaços em branco sejam incorporados acidentalmente na renderização, o que pode afetar o posicionamento e o alinhamento.

Por fim, observe de novo como usamos o tema de cores para garantir que essa adição mais recente ao mostrador do relógio mantenha o tema atual.

Como adicionar a contagem de passos

Substitua o texto  pelo seguinte:

<PartText x="0" y="0" width="225" height="225">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <TextCircular centerX="225" centerY="225" width="415" height="415" startAngle="270" endAngle="360" align="CENTER" direction="CLOCKWISE">
    <Font family="SYNC_TO_DEVICE" size="28" color="[CONFIGURATION.themeColor.2]">
      <Template>
        <![CDATA[%05d]]>
        <Parameter expression="[STEP_COUNT]"/>
      </Template>
    </Font>
  </TextCircular>
</PartText>

O Formato do Mostrador do Relógio é compatível com várias fontes de dados diferentes, e a contagem de passos é uma ótima adição a qualquer mostrador do relógio, permitindo que o usuário acompanhe o movimento e o exercício diário.

Crie e implante o mostrador do relógio para conferir as últimas adições:

9. Toques finais e prévia

A atenção aos detalhes é tudo nos mostradores do relógio. Por isso, vamos adicionar alguns toques finais.

Como adicionar uma sombra ao mostrador do relógio

Os ponteiros do mostrador do relógio funcionam bem juntos nas diferentes cores, mas parecem um pouco planos em relação ao mostrador. Substitua  pelo seguinte para adicionar sombras atrás dos ponteiros do relógio:

<HourHand resource="hour" x="220" y="55" width="20" height="190"
    pivotX="0.5" pivotY="0.921" tintColor="[CONFIGURATION.themeColor.4]">
  <Variant mode="AMBIENT" target="alpha" value="0" />
</HourHand>
<MinuteHand resource="minute" x="222" y="30" width="16" height="220"
    pivotX="0.5" pivotY="0.9" tintColor="[CONFIGURATION.themeColor.4]">
  <Variant mode="AMBIENT" target="alpha" value="0" />
</MinuteHand>
<SecondHand resource="second" x="226" y="20" width="8" height="245"
    pivotX="0.5" pivotY="0.857" tintColor="[CONFIGURATION.themeColor.4]">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <Sweep frequency="15" />
</SecondHand>

Como adicionar um logotipo divertido

Todos os fabricantes de relógios conhecidos têm o logotipo nos mostradores. Então, vamos adicionar o nosso. Naturalmente, vamos usar o logotipo do Android.

No entanto, como este é um smartwatch, vamos fazer diferente e adicionar um logotipo que se mova de acordo com o ângulo do pulso do usuário.

Para fazer isso, vamos colocar a imagem dentro de um elemento < Group> e usar um elemento < Transform> para aplicar uma rotação ao elemento <Group> com base no ângulo do pulso. Nossa estrutura vai ficar assim:

O ponto de rotação padrão de um elemento está no centro. Não é necessário ajustar os elementos pivotX e pivotY do <Group>. Aplicar um <Transform> ao <Group> vai girar o <PartImage> em torno desse ponto central.

No elemento <Transform>, usamos a fonte de dados [ ACCELEROMETER_ANGLE_XY], que representa a soma dos ângulos nas direções X e Y.

Substitua  pelo seguinte snippet:

<Group x="92" y="92" width="266" height="266" name="logo_container">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <Transform target="angle" mode="BY" value="0.1 * [ACCELEROMETER_ANGLE_XY]" />
  <PartImage x="97" y="0" width="72" height="72"
    tintColor="[CONFIGURATION.themeColor.2]">
    <Image resource="android"/>
  </PartImage>
</Group>

Implante o mostrador do relógio de novo. Se você estiver usando um dispositivo físico, coloque-o no pulso e mova o braço para ver o movimento do logotipo do Android. Se você estiver usando um emulador, abra os controles estendidos e manipule os ângulos X e Y nos sensores virtuais.

Como atualizar a prévia

No início do codelab, vimos que há um arquivo preview.png, que é usado pelo sistema para mostrar uma prévia do mostrador do relógio. Vamos atualizar isso para refletir melhor nosso mostrador finalizado.

A maneira mais fácil de gerar uma captura de tela é usando o emulador. Com o mostrador do relógio em execução, clique no botão de captura de tela:

Verifique se a captura está definida como Display Shape:

Salve a imagem e substitua o arquivo res/drawable/preview.png por ela. Recrie e implante o mostrador do relógio, como antes.

10. Parabéns

Parabéns! Você aprendeu os conceitos básicos de criação de um mostrador com o Formato do Mostrador do Relógio.

Solução para o codelab

O código da solução deste codelab está disponível no GitHub:

$ git clone https://github.com/android/codelab-watch-face-format