Criar um host de widgets

A tela inicial do Android, disponível na maioria dos dispositivos com esse sistema, 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 que um host aceita implicitamente.

Esta página se concentra nas responsabilidades envolvidas na implementação de um AppWidgetHost personalizado. Para um exemplo específico de como implementar um AppWidgetHost, consulte o código-fonte do widget de pesquisa da tela inicial do Android LauncherAppWidgetHost.

Confira uma visão geral das principais classes e conceitos envolvidos na implementação de um AppWidgetHost personalizado:

• Host de widget de app: o AppWidgetHost fornece a interação com o serviço AppWidget para apps que incorporam widgets na interface. Um AppWidgetHost precisa ter um ID exclusivo no próprio pacote do host. Esse ID persiste em todos os usos do host. O ID geralmente é um valor fixado no código que você atribui no app.

• ID do widget do app: cada instância de widget recebe um ID exclusivo no momento da vinculação. Consulte bindAppWidgetIdIfAllowed() e, para mais detalhes, a seção Como vincular widgets a seguir. O host recebe o ID exclusivo usando allocateAppWidgetId(). Esse ID persiste durante toda a vida útil do widget até que ele seja 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 do app: pense em AppWidgetHostView como um frame que envolve o widget sempre que ele precisa ser exibido. Um widget é associado a um AppWidgetHostView sempre que é inflado pelo host.

  • Por padrão, o sistema cria um AppWidgetHostView, mas o host pode criar a própria subclasse de AppWidgetHostView estendendo-a.
  • No Android 12 (nível 31 da API), o AppWidgetHostView introduz os métodos setColorResources() e resetColorResources() para processar cores sobrecarregadas dinamicamente. O host é responsável por fornecer as cores para esses métodos.

• Pacote de opções: o AppWidgetHost usa o pacote de opções para comunicar informações ao AppWidgetProvider 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 o AppWidgetProvider personalize o conteúdo e a aparência do widget com base em como e onde ele é exibido. É possível usar updateAppWidgetOptions() e updateAppWidgetSize() para modificar o pacote de um widget. Ambos os métodos acionam o callback onAppWidgetOptionsChanged() para o AppWidgetProvider.

Como vincular widgets

Quando um usuário adiciona um widget a um host, ocorre um processo chamado vinculação. A vinculação se refere à associação de um ID de widget de app específico a um host e a 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, o 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 permissão para que o app 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, o app precisará mostrar uma caixa de diálogo solicitando que o usuário conceda permissão: "permitir" para a adição atual do widget 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:

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Host.kt

O host precisa verificar se o widget adicionado por um usuário precisa de configuração. Para mais informações, consulte Permitir que os usuários configurem widgets de apps.

Responsabilidades do organizador

É possível especificar várias definições de configuração para widgets usando os metadados AppWidgetProviderInfo. É possível recuperar essas opções de configuração, abordadas em mais detalhes nas seções a seguir, do objeto AppWidgetProviderInfo associado a um provedor de widget.

Todos os hosts têm as seguintes responsabilidades:

• Ao adicionar um widget, aloque o ID dele conforme descrito anteriormente. Quando um widget é removido do host, chame deleteAppWidgetId() para desalocar o ID do widget.

• Ao adicionar um widget, verifique se a atividade de configuração precisa ser iniciada. Normalmente, o host precisa iniciar a atividade de configuração do widget, se ela existir e não estiver marcada como opcional, especificando as flags configuration_optional e reconfigurable. Consulte Atualizar o widget na atividade de configuração para mais detalhes. Essa é uma etapa necessária para que muitos widgets sejam exibidos.

  Observação: processe casos irregulares em que a atividade de configuração não retorna ou termina com erros.

• Os widgets especificam uma largura e altura padrão nos metadados AppWidgetProviderInfo. Esses valores são definidos em células (a partir do Android 12, se targetCellWidth e targetCellHeight forem especificados) ou dps, se apenas minWidth e minHeight forem especificados. Consulte Atributos de dimensionamento de widgets.

  O widget precisa ser 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 satisfazem as restrições minWidth e minHeight.

Dicas para sua abordagem

Além dos requisitos listados na seção anterior, lembre-se das seguintes dicas:

O pacote de opções pode conter um List<SizeF> que contém a lista de tamanhos possíveis em dps que uma instância de widget pode assumir. 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 dobráveis.

Há um limite de MAX_INIT_VIEW_COUNT (16) para o número de RemoteViews diferentes que um AppWidgetProvider pode fornecer ao RemoteViews. Como os objetos AppWidgetProvider mapeiam um objeto RemoteViews para cada tamanho no List<SizeF>, não forneça mais de MAX_INIT_VIEW_COUNT tamanhos.

Quando os widgets especificam os atributos maxResizeWidth e maxResizeHeight em dps, recomendamos que um widget que use pelo menos um desses atributos não exceda o tamanho especificado por eles.

Outros recursos

• Consulte a documentação de referência do Glance.