Como criar mostradores de relógio para o Wear OS
Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 de relógio manualmente usando XML ou que buscam entender melhor o formato para ajudar a criar as próprias ferramentas de design.

Se você quiser usar ferramentas gráficas para criar seu próprio mostrador de relógio, recomendamos conferir ferramentas disponíveis, 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 mais recente: 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 de 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 de sua preferência ou abrir o próprio projeto de início 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 conferir o que cada um faz:

Arquivo	Descrição
`AndroidManifest.xml`	Assim como em um app Android normal, este 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 de uma imagem de visualização usada pelo sistema. Para que esse projeto seja criado, a pasta start/ contém uma visualização em branco, que será atualizada 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 estão 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 do Wear OS lê esses recursos e cuida da criação e execução do mostrador do relógio para você. Isso significa que não é necessário ter um ambiente de execução ou outra lógica, o que economiza 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:

Que 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 visualização. Neste projeto, fornecemos uma imagem de visualização 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 XML do formato do mostrador do relógio

A definição do mostrador do relógio está contida em res/raw/watchface.xml. Inspecione esse arquivo no editor. O elemento <WatchFace> define uma largura e uma altura de 450 x 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 simplesmente "Hello, World!" no relógio. Mas vamos voltar para corrigir isso. Vamos criar o mostrador do relógio e colocá-lo 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 o mostrador do relógio e instalá-lo no dispositivo. Toque e pressione a tela do mostrador do relógio e encontre o mostrador Codelab. Como alternativa, para definir o mostrador do relógio usando a linha de comando:

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

O mostrador do relógio vai aparecer no relógio ou 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 conferir como adicionar um relógio analógico usando o elemento < AnalogClock>. Primeiro, remova todo o elemento < PartText> do arquivo watchface.xml e substitua-o 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 para recriar e implantar o mostrador do relógio no dispositivo ou emulador:

./gradlew installDebug

Dessa vez, temos um relógio que funciona, mas ainda podemos melhorar muito.

5. Como adicionar cores e temas

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

No momento, nosso mostrador de relógio é um pouco simples, todo branco. Vamos adicionar um pouco de cor! Além disso, vamos personalizar os temas de cores.

Como criar a ColorConfiguration

Primeiro, vamos definir os temas de cores que vão estar 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 seis temas de cores, cada um com cinco cores. Cada tema é uma lista de cores separada por espaços, conforme mostrado no atributo colors.

Cada um dos temas precisa de um nome fácil de entender. Portanto, 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 a 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 no tema selecionado, o <MinuteHand> à segunda cor e o <SecondHand> à terceira.

Reproduza e implante o mostrador do relógio, como antes, e você vai notar que ele agora 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 seis temas de cores.

6. Como adicionar uma cor de plano de fundo

Há mais algumas coisas que podemos fazer para destacar esse mostrador. Vamos adicionar um design de plano de fundo em negrito. Embora o plano de fundo continue predominantemente preto, esse toque de cor ajuda a melhorar o visual.

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> novamente: isso vai remover nosso anel de segundo plano no modo ambiente para minimizar o número de pixels acesos.

Observe também como estamos usando o tema de cores novamente 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 a correção do XML, economizando tempo na criação e implantação de um mostrador do relógio para descobrir que ele 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, uma mensagem de confirmação vai aparecer. No entanto, se um erro for encontrado, os detalhes do erro e o local vão ser exibidos, 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 para realizar operações de texto.

Como adicionar a data

Substitua o texto  por este:

<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. Portanto, usamos a expressão de formatação %d %s para colocar o número inteiro e a string juntos.

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

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

Como adicionar a contagem de passos

Substitua o texto  por este:

<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 adições mais recentes:

9. Toques finais e visualização

A atenção aos detalhes é tudo em mostradores de relógio. Vamos adicionar alguns detalhes finais.

Como adicionar 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 deles nos mostradores. Vamos adicionar o nosso! Naturalmente, vamos usar o logotipo do Android.

No entanto, como este é um smartwatch, vamos fazer algo diferente e adicionar um logotipo que se move 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> faz com que o <PartImage> gire 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 novamente. Se você estiver usando um dispositivo físico, coloque-o e mova o pulso para ver o logotipo do Android se mover. Se você estiver usando um emulador, abra os controles estendidos e manipule os ângulos X e Y nos sensores virtuais.

Como atualizar a visualização

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 Forma de exibição:

Salve a imagem e substitua o arquivo res/drawable/preview.png por essa nova imagem. Crie 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