Uma complicação é qualquer recurso do mostrador do relógio que é exibido além do horário. Por exemplo, o indicador de bateria é uma complicação. A API Complications é destinada a mostradores de relógio e a apps de provedores de dados.
Confira os seguintes recursos relacionados:
O restante deste documento descreve provedores de dados, mostradores de relógio e tipos de complicações.
Provedores de dados de complicação
Apps que disponibilizam dados (como o nível da bateria, o clima ou dados de contagem de passos) a mostradores de relógio são chamados de “provedores de dados de complicação”. Esses provedores de dados disponibilizam dados brutos e não são responsáveis por controlar o modo como as próprias informações são renderizadas em um mostrador do relógio. Para gravar apps que disponibilizem dados a mostradores de relógio, consulte Expor dados a complicações.
Conforme mostrado no diagrama abaixo, o Wear OS by Google media o fluxo de dados dos provedores aos mostradores de relógio.

Complicações em mostradores de relógio
Mostradores de relógios recebem dados de provedores de dados de complicação, o que permite que eles incluam complicações sem precisar de código para coletar os dados subjacentes. Mostradores de relógio mantêm o controle sobre como os dados são renderizados. Assim, eles podem integrar os dados naturalmente com o próprio design. Confira os padrões de design para complicações.
Para saber como adicionar complicações a um mostrador do relógio, consulte Adicionar complicações a um mostrador de relógio.
Tipos de complicação
Os tipos de complicação definem quais dados podem ser mostrados em uma complicação ou disponibilizados por um provedor de dados. Por exemplo, o tipo SHORT_TEXT é usado quando os dados consistem principalmente em uma string curta. Um objeto ComplicationData sempre terá um único tipo de complicação que define os campos obrigatórios e opcionais. Geralmente, um campo obrigatório representa os dados principais. A maioria dos tipos adota o nome do campo obrigatório.
Provedores de dados usam esses tipos de complicação de forma diferente dos mostradores de relógio:
- Um provedor de dados escolhe os tipos de dados de complicação a serem disponibilizados (inclusive quais campos opcionais desses tipos serão disponibilizados) e quantos tipos diferentes podem ser aceitos. Por exemplo, um provedor de contagem de passos pode ser compatível com os tipos RANGED_VALUE e SHORT_TEXT, enquanto um provedor de “próximo encontro” pode ser compatível com os tipos SHORT_TEXT e LONG_TEXT.
- Você pode escolher quantas complicações serão incluídas no mostrador do relógio e os tipos de complicação compatíveis. Por exemplo, uma complicação de discagem em um mostrador de relógio pode ser compatível com os tipos SHORT_TEXT, ICON e RANGED_VALUE, enquanto um medidor no mostrador do relógio pode ser compatível apenas com o tipo RANGED_VALUE.
Para saber mais sobre os diferentes tipos de complicação e os campos compatíveis com cada tipo, consulte Usar e testar tipos de complicação.
Resumo da API
Veja abaixo um resumo da API Complications, que faz parte da Biblioteca de Suporte para Wearable. Consulte a Referência da API Wear.
-
ComplicationData
- Analisável (usando um Bundle internamente); imutável
- Representa todos os tipos de dados de complicação
- Inclui um builder para criação de instâncias
-
ComplicationDrawable
- Permite que você renderize uma complicação inteira em um canvas
-
ComplicationHelperActivity
- Usado para solicitar a seguinte permissão:
com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
- Usado em vez de
ProviderChooserIntent
para iniciar o seletor em quase todos os casos
- Usado para solicitar a seguinte permissão:
-
ComplicationManager
- Um wrapper para o serviço de gerenciamento de complicações, destinado a provedores
- Permite que os provedores enviem dados de complicação para o sistema
-
ComplicationProviderService
- Estende
Service
e inclui métodos de callback para responder ao sistema de complicações - Métodos de callback são chamados no thread principal
- Estende
-
ComplicationText
- Usado para disponibilizar valores de texto em um objeto
ComplicationData
- Inclui opções para valores que dependem do horário atual
- Usado para disponibilizar valores de texto em um objeto
-
ProviderChooserIntent
- Classe de utilitário não instanciável que não é comumente usada; prefira
ComplicationHelperActivity
- Classe de utilitário não instanciável que não é comumente usada; prefira
-
ProviderInfoRetriever
- Pode ser usado (por atividades de configuração do mostrador do relógio) para recuperar as informações do provedor de dados atual (app, nome do provedor, ícone) para todas as complicações pertencentes a um mostrador de relógio
-
ProviderUpdateRequester
- Pode ser usado por apps de provedores de dados para acionar chamadas para
onComplicationUpdated
no serviço do provedor para permitir o envio de atualizações
- Pode ser usado por apps de provedores de dados para acionar chamadas para
-
SystemProviders
- Lista os provedores de sistema considerados “seguros” por oferecerem apenas as informações que o mostrador do relógio pode coletar por conta própria
-
TextRenderer
- Facilita o desenho de texto em um canvas
Além disso, a classe WatchFaceService.Engine
contém os seguintes métodos:
-
setActiveComplications()
- Precisa ser chamado pelo mostrador do relógio para informar o objeto
ComplicationManager
sobre quais slots de complicação estão disponíveis e quais tipos são compatíveis
- Precisa ser chamado pelo mostrador do relógio para informar o objeto
-
onComplicationDataUpdate()
- Chamado pelo objeto
ComplicationManager
para enviar dados de complicação para o mostrador do relógio
- Chamado pelo objeto
-
setDefaultSystemComplicationProvider()
- Define o provedor de sistema padrão para uma complicação.
Esse método aceita um ID (como um número inteiro) para um provedor de sistema.
Os IDs disponíveis são listados na classe
SystemProviders
.
- Define o provedor de sistema padrão para uma complicação.
Esse método aceita um ID (como um número inteiro) para um provedor de sistema.
Os IDs disponíveis são listados na classe