Configuração do formato do mostrador do relógio

Observação: esta página mostra uma etapa do processo de gerenciamento manual da configuração do mostrador do relógio. Se você quiser criar o design do mostrador do relógio usando uma ferramenta WYSIWYG (o que você vê é o que você recebe), confira primeiro os guias do Watch Face Studio.

Este guia inclui etapas sobre as ferramentas necessárias para configurar um mostrador de relógio usando o formato de mostrador do relógio, algumas sugestões sobre a estrutura do projeto e um guia detalhado para aplicar as ferramentas e criar essa estrutura.

Começar a usar o Android Studio

A maneira mais fácil de começar a desenvolver mostradores de relógio manualmente é usar o Android Studio. O suporte a mostradores do relógio está disponível no canal Canary.

  1. Clique em Arquivo > Novo projeto.
  2. Em Wear OS, selecione Mostrador do relógio básico.

Isso cria a estrutura necessária para um mostrador do relógio totalmente funcional.

Estrutura do projeto

Quando você cria um mostrador personalizado que usa o formato de mostrador do relógio, o Android App Bundle que inclui o arquivo de mostrador personalizado precisa ser completamente separado do Android App Bundle que contém a lógica do seu app para Wear OS. Algumas app stores, incluindo o Google Play, impedem que você faça upload de um Android App Bundle que inclua a lógica do Wear OS e um mostrador do relógio personalizado.

Declarar a versão do Formato do mostrador do relógio

No arquivo de manifesto do novo app (AndroidManifest.xml), inspecione a propriedade que indica o uso do formato do mostrador do relógio.

Alguns recursos do formato de mostrador do relógio estão disponíveis apenas em versões mais recentes. Defina essa propriedade com o menor valor que oferece suporte aos recursos necessários para maximizar a compatibilidade do dispositivo e também defina o minSdkVersion para corresponder. Saiba mais sobre como configurar versões do seu app.

<manifest ...>
    <!--
        Use SDK version 33 to support Watch Face Format (WFF) version 1 and
        higher, SDK version 34 to support WFF version 2 and higher, and so on.
    -->
    <uses-sdk
        android:minSdkVersion="34"
        android:targetSdkVersion="34" />

    <!--
        WFF is a resource-only format, so the hasCode attribute should be set to
        false to reflect this.
    -->
    <application
        android:label="@string/watch_face_name"
        android:hasCode="false"
        ...>
        <meta-data android:name="com.google.android.wearable.standalone"
            android:value="true" />
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="2" />
    </application>
</manifest>

Declarar metadados do mostrador do relógio

No diretório de recursos res/xml do app, há um arquivo chamado watch_face_info.xml. É nesse arquivo que você define os metadados do mostrador do relógio:

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>

    <Preview value="@drawable/watch_face_preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
</WatchFaceInfo>

Os campos do arquivo representam os seguintes detalhes:

Preview
Faz referência ao drawable que contém uma imagem de visualização do mostrador do relógio.
Category

Define a categoria do mostrador do relógio. Precisa ser uma string ou uma referência a uma string, como @string/ref_name. Cada fabricante de dispositivo pode definir o próprio conjunto de categorias de mostradores de relógio.

Valor padrão: empty_category_meta, que agrupa esse mostrador do relógio com outros mostradores de "categoria vazia" na parte de baixo da visualização do seletor.

AvailableInRetail

Indica se o mostrador do relógio está disponível no modo de demonstração na loja do dispositivo. Precisa ser um valor booleano ou uma referência a um valor booleano como @bool/watch_face_available_in_retail.

Valor padrão: false

MultipleInstancesAllowed

Indica se o mostrador do relógio pode ter vários favoritos. Precisa ser um valor booleano ou uma referência a um valor booleano, como @bool/watch_face_multiple_instances_allowed.

Valor padrão: false

Editable

Indica se o mostrador do relógio é editável, o que significa que ele tem uma configuração ou pelo menos um complemento não fixa. Isso é usado para mostrar ou ocultar o botão Edit do mostrador do relógio na lista de favoritos.

Valor padrão: false

Declarar o nome do mostrador do relógio

No arquivo de manifesto do app (AndroidManifest.xml), defina o atributo android:label como o nome do mostrador do relógio:

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

Declarar detalhes do mostrador do relógio

A estrutura de um documento básico de mostrador do relógio WFF é a seguinte:

<WatchFace width="450" height="450">
  <Scene>
    <!-- Content to be rendered -->
  </Scene>
</WatchFace>

O modelo do Android Studio fornece um documento básico em res/raw/watchface.xml. Para oferecer suporte a diferentes formatos e tamanhos de tela, declare suporte a vários formatos e tamanhos.

O elemento raiz é sempre WatchFace. Os elementos height e width definem a extensão do espaço de coordenadas para uso no mostrador do relógio, que é dimensionado para se ajustar ao dispositivo em que está sendo usado. height e width não representam pixels reais.

O Formato do mostrador do relógio organiza vários detalhes sobre o mostrador:

  • Metadados, como a hora e a contagem de passos mostradas na imagem de prévia do mostrador do relógio.
  • Configurações do usuário, como diferentes temas de cores para o mostrador do relógio, elementos que podem ser ativados/desativados pelo usuário e uma escolha entre vários elementos. A versão 2 do Formato do Mostrador do Relógio apresenta sabores, que podem aparecer em uma configuração do usuário. Cada opção especifica uma configuração de usuário predefinida, especificando o tipo e o estilo dos elementos que aparecem com a hora no mostrador do relógio. Com essas predefinições, é mais fácil criar grupos de elementos visualmente agradáveis. No app complementar do Wear OS, os usuários veem os diferentes estilos do mostrador do relógio em uma linha rolável.
  • Uma cena que contém os elementos visuais de um mostrador do relógio. Os elementos que aparecem mais perto do final da cena ficam sobre outros elementos. Portanto, a ordem típica é a seguinte:
    • Os ponteiros de um relógio analógico ou o texto de um relógio digital
    • Complementos que mostram informações adicionais, como o dia da semana ou a contagem de passos de um usuário
    • Outros gráficos que oferecem interesse visual ou decorações para o mostrador do relógio, como uma imagem de um acampamento
  • Grupos de elementos, que permitem modificar vários elementos ao mesmo tempo. É possível criar variantes desses grupos em uma cena, o que permite ocultar ou modificar seletivamente o conteúdo quando o sistema entra em um modo ambiente de economia de energia.

Os atributos são fortemente definidos e têm diretrizes sobre frequência e valores válidos para evitar a maioria dos erros comuns ao criar um mostrador de relógio.

Declarar suporte a formas do mostrador do relógio (opcional)

Essa etapa só é necessária se você quiser oferecer suporte a comportamentos diferentes para diferentes tamanhos de mostradores de relógio. Pule esta etapa se quiser que o mostrador do relógio seja dimensionado de acordo com o tamanho do relógio.

No diretório de recursos res/xml do app, declare o conjunto de formas aceitas do mostrador do relógio em watch_face_shapes.xml:

<WatchFaces>
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
<WatchFaces>

Em seguida, defina a aparência e o comportamento do mostrador do relógio para cada formato. Se você não definiu um arquivo de formas, só precisa de um arquivo, watchface.xml.

Usando o exemplo desta seção, os arquivos XML brutos seriam:

  • res/raw/watchface.xml
  • res/raw/watchface_large_circle.xml

Identificar o editor do mostrador do relógio (opcional)

Como opção, declare uma string arbitrária no arquivo de manifesto do seu app para identificar o editor do mostrador do relógio ou o nome e a versão da ferramenta que você está usando:

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="<var>{toolName}-{toolVersion}</var>" />
</application>

Verificar a correção e o desempenho do mostrador do relógio

Durante o desenvolvimento e antes de fazer upload para o Google Play, verifique se o mostrador do relógio não tem erros de sintaxe usando a validação integrada do Formato do Mostrador do Relógio no Android Studio. Isso destaca automaticamente os erros no seu código e reconhece a versão.

Você também precisa verificar se o mostrador do relógio atende aos requisitos de uso de memória executando a ferramenta consumo de memória.

Criar o pacote de apps do mostrador do relógio

A maneira mais fácil de criar e implantar o mostrador do relógio é pelo Android Studio, que tem suporte integrado para configurações de execução do mostrador do relógio. Depois de clicar no botão Executar, o Android Studio implanta o mostrador do relógio no dispositivo ou emulador e o define como o mostrador ativo.

Exemplos de mostradores de relógio

Outros exemplos de projetos do formato de mostrador do relógio estão disponíveis no GitHub.