Criar um widget simples

Experimente trabalhar com o Compose
O Jetpack Compose é o kit de ferramentas de interface recomendado para o Android. Aprenda a criar widgets usando APIs no estilo do Compose.
Jetpack Glance →

Widgets de apps são visualizações de aplicativos em miniatura que podem ser incorporadas em outros apps (como a tela inicial) e receber atualizações periódicas. Essas visualizações são chamadas de widgets na interface do usuário, e é possível publicá-las com um provedor de widgets de apps (ou provedor de widgets). Um componente de app que contém outros widgets é chamado de host de widgets de apps (ou host de widgets). A Figura 1 mostra um exemplo de widget de música:

Exemplo de widget de música
Figura 1. Exemplo de um widget de música.

Este documento descreve como publicar um widget usando um provedor. Para mais detalhes sobre como criar seu próprio AppWidgetHost para hospedar widgets de apps, consulte Criar um host de widgets.

Para saber como projetar seu widget, consulte Visão geral dos widgets de apps.

Componentes de widget

Para criar um widget, você precisa dos seguintes componentes básicos:

AppWidgetProviderInfo objeto
Descreve os metadados de um widget, como o layout, a frequência de atualização e a AppWidgetProvider classe. AppWidgetProviderInfo é definido em XML, conforme descrito neste documento.
AppWidgetProvider classe
Define os métodos básicos que permitem a interface programática com o widget. Por meio dele, você recebe transmissões quando o widget é atualizado, ativado, desativado ou excluído. Você declara AppWidgetProvider no manifesto e então implementa, conforme descrito neste documento.
Ver layout
Define o layout inicial do widget. O layout é definido em XML, conforme descrito neste documento.

A Figura 2 mostra como esses componentes se encaixam no fluxo geral de processamento de widgets de apps.

Fluxo de processamento de widgets de apps
Figura 2. Fluxo de processamento de widgets de apps.

Se o widget precisar da configuração do usuário, implemente a atividade de configuração do widget de app. Essa atividade permite que os usuários modifiquem as configurações do widget, por exemplo, o fuso horário de um widget de relógio.

Também recomendamos as seguintes melhorias: layouts de widgets flexíveis, melhorias diversas, widgets avançados, widgets de coleção e criação de um host de widgets.

Declarar o XML AppWidgetProviderInfo

A definição das configurações de metadados (como tamanhos de células padrão, restrições de redimensionamento e frequências de atualização) é exatamente idêntica em widgets tradicionais e baseados no Glance.

Para saber como definir e configurar o arquivo XML de metadados, consulte a seção Declarar o XML AppWidgetProviderInfo do Compose-first na documentação do Glance.

Usar a classe AppWidgetProvider para processar transmissões de widgets

Os mecanismos de broadcast receiver da plataforma, os filtros de declaração de manifesto e os loops de eventos de ciclo de vida são unificados na plataforma. No desenvolvimento do Compose-first, essas transmissões são orquestradas usando o wrapper GlanceAppWidgetReceiver.

Para entender como registrar seu receiver no manifesto e implementar substituições de ciclo de vida compatíveis com o Hilt, consulte a seção do Compose-first Usar a classe AppWidgetProvider para processar transmissões na documentação do Glance.

Criar o layout do widget

É necessário definir um layout inicial para o widget em XML e salvá-lo no diretório res/layout/ do projeto. Consulte as diretrizes de design para mais detalhes.

Criar o layout do widget é simples se você estiver familiarizado com layouts. No entanto, os layouts de widgets são baseados em RemoteViews, que não oferece suporte a todos os tipos de layout ou widget de visualização. Não é possível usar visualizações personalizadas ou subclasses das visualizações com suporte de RemoteViews.

RemoteViews também oferece suporte a ViewStub, que é uma invisível e de tamanho zeroView que pode ser usada para inflar lentamente os recursos de layout no momento da execução.

Suporte a comportamentos com estado

O Android 12 adiciona suporte a comportamentos com estado usando os componentes existentes a seguir:

O widget ainda não tem estado. O app precisa armazenar o estado e se registrar para eventos de mudança de estado.

Exemplo de widget de lista de compras mostrando comportamento com estado
Figura 3. Exemplo de comportamento com estado.

O exemplo de código a seguir mostra como implementar esses componentes.

Kotlin

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

Java

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

Forneça dois layouts: um destinado a dispositivos com o Android 12 ou mais recente em res/layout-v31, e o outro destinado ao Android 11 ou versões anteriores na pasta res/layout padrão.

Implementar cantos arredondados

O cálculo do plano de fundo externo e dos raios proporcionais internos é padrão e compartilhado. No desenvolvimento do Compose-first, isso pode ser definido dinamicamente no Kotlin, juntamente com recursos de tema personalizados.

Para implementar raios de canto ou configurar estilos dinâmicos para dispositivos Android mais antigos, consulte a seção Implementar cantos arredondados do Compose-first na documentação do Glance.