Criar um widget simples

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

Os widgets de apps são visualizações em miniatura que podem ser incorporadas em outros apps, como a tela inicial, e recebem atualizações periódicas. Essas visualizações são chamadas de widgets na interface do usuário, e é possível publicar uma com um provedor de widgets de app (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 de widgets. Para detalhes sobre como criar seu próprio AppWidgetHost para hospedar widgets de apps, consulte Criar um host de widgets.

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

Componentes de widget

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

Objeto AppWidgetProviderInfo
Descreve os metadados de um widget, como o layout, a frequência de atualização e a classe AppWidgetProvider. AppWidgetProviderInfo é definido em XML, conforme descrito neste documento.
Classe AppWidgetProvider
Define os métodos básicos que permitem interagir programaticamente com o widget. Por meio dela, você recebe transmissões quando o widget é atualizado, ativado, desativado ou excluído. Você declara AppWidgetProvider no manifesto e depois 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 app.

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

Se o widget precisar de 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

Definir as configurações de metadados (como tamanhos de células padrão, restrições de redimensionamento e frequências de atualização) é exatamente igual nas visualizações tradicionais e nos widgets baseados em resumo.

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

Usar a classe AppWidgetProvider para processar transmissões de widgets

Os mecanismos de broadcast receiver, os filtros de declaração de manifesto e os loops de eventos de ciclo de vida da plataforma são unificados nela. No desenvolvimento com Compose em primeiro lugar, essas transmissões são organizadas usando o wrapper GlanceAppWidgetReceiver.

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

Criar o layout do widget

É necessário definir um layout inicial para seu 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ê conhecer os layouts. No entanto, os layouts de widgets são baseados em RemoteViews, que não é compatível com todos os tipos de layout ou widget de visualização. Não é possível usar visualizações personalizadas ou subclasses das visualizações compatíveis com RemoteViews.

O RemoteViews também é compatível com ViewStub, que é uma View invisível e de tamanho zero que pode ser usada para inflar lentamente os recursos de layout no momento da execução.

Suporte para comportamento com estado

O Android 12 adiciona suporte a comportamentos com estado usando os seguintes componentes atuais:

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 direcionado a dispositivos com Android 12 ou versões mais recentes em res/layout-v31 e outro direcionado a versões anteriores do Android 11 ou 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 com Compose em primeiro lugar, isso pode ser definido dinamicamente em Kotlin junto 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 Glance na documentação do Compose-first.