Criar um widget básico

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

Os widgets de apps são visualizações em miniatura de apps 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 você pode 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 projetar seu widget, consulte Visão geral dos widgets de apps.

Componentes do 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 de forma programática com o widget. Com ela, você recebe transmissões quando o widget é atualizado, ativado, desativado ou excluído. Declare AppWidgetProvider no manifesto e, em seguida, implemente-o, 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 do widget do app.

Se o widget precisar de configuração do usuário, implemente a atividade de configuração do widget do 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 widget flexíveis, melhorias diversas, widgets avançados, widgets de coleção e criação de um host de widget.

Declarar o XML AppWidgetProviderInfo

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

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

Usar a classe AppWidgetProvider para processar transmissões de widgets

A mecânica do broadcast receiver, os filtros de declaração de manifesto e os loops de eventos de ciclo de vida da plataforma são unificados. No desenvolvimento prioritário do Compose, essas transmissões são orquestradas usando o wrapper GlanceAppWidgetReceiver.

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

Criar o layout do widget

É preciso 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ê já conhece os layouts. No entanto, os layouts de widget 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 compatíveis com RemoteViews.

O RemoteViews também é compatível com ViewStub, que é uma View invisível e com 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 ao comportamento com estado usando os seguintes componentes:

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.

// 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 para dispositivos com o Android 12 ou mais recente em res/layout-v31 e outro para o Android 11 ou versões anteriores na pasta padrão res/layout.

Implementar cantos arredondados

O cálculo dos raios proporcionais interno e do plano de fundo externo é padrão e compartilhado. No desenvolvimento que prioriza o Compose, isso pode ser definido dinamicamente no Kotlin 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 na documentação do Glance.