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.

Clique em Arquivo > Novo projeto.
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.

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

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 defina o minSdkVersion para corresponder. Saiba mais sobre como configurar versões do seu app.

O elemento <application> também precisa incluir o atributo android:hasCode="false". Os pacotes do Formato do Mostrador do Relógio são apenas de recursos e não podem conter nenhum código.

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:

<WatchFaceInfo>
    <Preview value="@drawable/preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
    <FlavorsSupported value="true" />
</WatchFaceInfo>watch_face_info.xml

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 no elemento application como o nome do mostrador do relógio.

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>watchface_basic.xml

O modelo do Android Studio oferece 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 variante 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 do 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_basic"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
        file="@raw/watchface"/>
</WatchFaces>watch_face_shapes.xml

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_basic.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:

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

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.

Saiba mais sobre otimizar o uso da memória e verificar o uso da memória em preparação para a publicação.
Saiba mais sobre como usar o validador de XML como parte do seu ciclo de desenvolvimento.

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.