A tela inicial do Android, disponível na maioria dos dispositivos Android, permite que o
usuário incorpore widgets de apps (ou widgets) para
acesso rápido ao conteúdo. Se você estiver criando uma substituição de tela inicial ou um
app semelhante, também poderá permitir que o usuário incorpore widgets implementando
AppWidgetHost
. Isso não é
algo que a maioria dos apps precisa fazer, mas, se você estiver criando seu próprio host, é
importante entender as obrigações contratuais com as quais um host concorda implicitamente.
Esta página se concentra nas responsabilidades envolvidas na implementação de um AppWidgetHost
personalizado. Para ver um exemplo específico de como implementar um AppWidgetHost
,
consulte o código-fonte da tela inicial do Android
LauncherAppWidgetHost
.
Esta é uma visão geral dos principais conceitos e classes envolvidos na implementação de um
AppWidgetHost
personalizado:
Host de widgets de apps: o
AppWidgetHost
fornece a interação com o serviço AppWidget para apps que incorporam widgets na interface. OAppWidgetHost
precisa ter um ID exclusivo no pacote do host. Esse ID persiste em todos os usos do host. O ID normalmente é um valor fixado no código que você atribui no app.ID do widget de app: cada instância de widget recebe um ID exclusivo no momento da vinculação. Consulte
bindAppWidgetIdIfAllowed()
e, para mais detalhes, a seção Vincular widgets a seguir. O host recebe o ID exclusivo usandoallocateAppWidgetId()
. Ele persiste durante o ciclo de vida do widget até ser excluído do host. Qualquer estado específico do host, como o tamanho e o local do widget, precisa ser mantido pelo pacote de hospedagem e associado ao ID do widget do app.Visualização do host do widget de app: pense em
AppWidgetHostView
como um frame em que o widget será encapsulado sempre que precisar ser exibido. Um widget é associado a umAppWidgetHostView
sempre que ele é inflado pelo host.- Por padrão, o sistema cria uma
AppWidgetHostView
, mas o host pode criar a própria subclasse deAppWidgetHostView
estendendo-a. - No Android 12 (nível 31 da API) e versões mais recentes, a
AppWidgetHostView
introduz os métodossetColorResources()
eresetColorResources()
para processar cores sobrecarregadas dinamicamente. O host é responsável por fornecer as cores para esses métodos.
- Por padrão, o sistema cria uma
Pacote de opções: o
AppWidgetHost
usa o pacote de opções para comunicar informações aoAppWidgetProvider
sobre como o widget é exibido (por exemplo, a lista de intervalos de tamanho) e se o widget está em uma tela de bloqueio ou na tela inicial. Essas informações permitem que oAppWidgetProvider
personalize o conteúdo e a aparência do widget com base em como e onde ele é mostrado. Você pode usarupdateAppWidgetOptions()
eupdateAppWidgetSize()
para modificar o pacote de um widget. Os dois métodos acionam o callbackonAppWidgetOptionsChanged()
para oAppWidgetProvider
.
Vincular widgets
Quando um usuário adiciona um widget a um host, ocorre um processo chamado vinculação. Vinculação
refere-se à associação de um determinado ID de widget de app a um host e um
AppWidgetProvider
específicos.
As APIs de vinculação também permitem que um host forneça uma interface personalizada para
vinculação. Para usar esse processo, seu app precisa declarar a permissão
BIND_APPWIDGET
no manifesto do host:
<uses-permission android:name="android.permission.BIND_APPWIDGET" />
No entanto, esse é apenas o primeiro passo. No momento da execução, o usuário precisa conceder explicitamente
a permissão ao app para que ele adicione um widget ao host. Para testar se o
app tem permissão para adicionar o widget, use o
método
bindAppWidgetIdIfAllowed()
. Se bindAppWidgetIdIfAllowed()
retornar false
, seu app precisará exibir uma
caixa de diálogo solicitando que o usuário conceda a permissão: "permitir" para a adição do widget atual
ou "sempre permitir" para abranger todas as adições futuras de widgets.
Este snippet demonstra um exemplo de como exibir a caixa de diálogo:
Kotlin
val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply { putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName) // This is the options bundle described in the preceding section. putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options) } startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Java
Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName); // This is the options bundle described in the preceding section. intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options); startActivityForResult(intent, REQUEST_BIND_APPWIDGET);
O host precisa verificar se o widget adicionado pelo usuário precisa ser configurado. Para mais informações, consulte Permitir que os usuários configurem widgets de apps.
Responsabilidades do organizador
Você pode especificar várias configurações para widgets usando os
metadados AppWidgetProviderInfo
.
É possível recuperar essas opções de configuração, abordadas em mais detalhes nas
seções a seguir, usando o objeto
AppWidgetProviderInfo
associado a um provedor de widgets.
Seja qual for a versão do Android de destino, todos os hosts têm as responsabilidades abaixo:
Ao adicionar um widget, aloque o ID dele conforme descrito anteriormente. Quando um widget for removido do host, chame
deleteAppWidgetId()
para desalocar o ID do widget.Ao adicionar um widget, confira se a atividade de configuração precisa ser iniciada. Normalmente, o host precisa iniciar a atividade de configuração do widget, se houver e não estiver marcado como opcional, especificando as sinalizações
configuration_optional
ereconfigurable
. Consulte Atualizar o widget pela atividade de configuração para saber mais. Essa é uma etapa necessária para muitos widgets antes que eles possam ser exibidos.Os widgets especificam uma largura e uma altura padrão nos metadados
AppWidgetProviderInfo
. Esses valores são definidos em células, a partir do Android 12, setargetCellWidth
etargetCellHeight
forem especificados, ou dps, se apenasminWidth
eminHeight
forem especificados. Consulte Atributos de dimensionamento do widget.Confira se o widget está disposto com pelo menos essa quantidade de dps. Por exemplo, muitos hosts alinham ícones e widgets em uma grade. Nesse cenário, por padrão, o host adiciona um widget usando o número mínimo de células que atenda às restrições
minWidth
eminHeight
.
Além dos requisitos listados na seção anterior, versões específicas da plataforma introduzem recursos que colocam novas responsabilidades no host.
Determine sua abordagem com base na versão do Android de destino
Android 12
O Android 12 (nível 31 da API) empacota uma List<SizeF>
extra que contém a lista
de tamanhos possíveis em dps que uma instância de widget pode assumir no pacote de opções.
O número de tamanhos fornecidos depende da implementação do host. Os hosts normalmente
oferecem dois tamanhos para smartphones (retrato e paisagem) e quatro tamanhos
para dispositivos dobráveis.
Há um limite de MAX_INIT_VIEW_COUNT
(16) para o número de RemoteViews
diferentes que um AppWidgetProvider
pode fornecer a
RemoteViews
.
Como objetos AppWidgetProvider
mapeiam um objeto RemoteViews
para cada tamanho no
List<SizeF>
, não forneça mais de MAX_INIT_VIEW_COUNT
tamanhos.
O Android 12 também introduz os atributos
maxResizeWidth
e
maxResizeHeight
em dps. Recomendamos que um widget que usa pelo menos um desses
atributos não exceda o tamanho especificado pelos atributos.
Outros recursos
- Consulte a documentação de referência do
Glance
.