Esta página descreve refinamentos no dimensionamento de widgets e maior flexibilidade introduzidas no Android 12 (nível 31 da API). Ele também detalha como determinar um tamanho para o widget.
Usar APIs melhoradas para tamanhos e layouts de widgets
A partir do Android 12 (nível 31 da API), é possível fornecer atributos de tamanho mais refinados e layouts flexíveis fazendo o seguinte, conforme descrito nas seções a seguir:
Especifique outras restrições de dimensionamento de widgets.
Fornecer layouts responsivos ou layouts exatos.
Nas versões anteriores do Android, é possível acessar as faixas de tamanho de um
widget usando os extras
OPTION_APPWIDGET_MIN_WIDTH
,
OPTION_APPWIDGET_MIN_HEIGHT
,
OPTION_APPWIDGET_MAX_WIDTH
e OPTION_APPWIDGET_MAX_HEIGHT
e estimar o tamanho do widget, mas essa lógica não funciona em todas as
situações. Para widgets destinados ao Android 12 ou versões mais recentes, recomendamos
fornecer layouts responsivos ou exatos.
Especificar outras restrições de dimensionamento do widget
O Android 12 adiciona APIs para garantir que o widget seja dimensionado de maneira mais confiável em diferentes dispositivos com diversos tamanhos de tela.
Além dos atributos minWidth
,
minHeight
,
minResizeWidth
,
e minResizeHeight
,
use os novos atributos appwidget-provider
a seguir:
targetCellWidth
etargetCellHeight
: definem o tamanho de destino do widget em termos de células de grade na tela de início. Se definidos, esses atributos serão usados em vez deminWidth
ouminHeight
.maxResizeWidth
emaxResizeHeight
: definem o tamanho máximo que a tela de início permite que o usuário redimensione o widget.
O XML a seguir mostra como usar os atributos de dimensionamento.
<appwidget-provider
...
android:targetCellWidth="3"
android:targetCellHeight="2"
android:maxResizeWidth="250dp"
android:maxResizeHeight="110dp">
</appwidget-provider>
Fornecer layouts responsivos
Se o layout precisar mudar dependendo do tamanho do widget, recomendamos criar um pequeno conjunto de layouts, cada um válido para uma série de tamanhos. Se isso não for possível, outra opção é fornecer layouts com base no tamanho exato do widget durante a execução, conforme descrito nesta página.
Esse recurso permite um escalonamento mais suave e uma melhor integridade do sistema, já que o sistema não precisa ativar o app sempre que ele exibir o widget em um tamanho diferente.
O exemplo de código a seguir mostra como fornecer uma lista de layouts.
Kotlin
override fun onUpdate(...) { val smallView = ... val tallView = ... val wideView = ... val viewMapping: Map<SizeF, RemoteViews> = mapOf( SizeF(150f, 100f) to smallView, SizeF(150f, 200f) to tallView, SizeF(215f, 100f) to wideView ) val remoteViews = RemoteViews(viewMapping) appWidgetManager.updateAppWidget(id, remoteViews) }
Java
@Override public void onUpdate(...) { RemoteViews smallView = ...; RemoteViews tallView = ...; RemoteViews wideView = ...; Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>(); viewMapping.put(new SizeF(150f, 100f), smallView); viewMapping.put(new SizeF(150f, 200f), tallView); viewMapping.put(new SizeF(215f, 100f), wideView); RemoteViews remoteViews = new RemoteViews(viewMapping); appWidgetManager.updateAppWidget(id, remoteViews); }
Suponha que o widget tenha os seguintes atributos:
<appwidget-provider
android:minResizeWidth="160dp"
android:minResizeHeight="110dp"
android:maxResizeWidth="250dp"
android:maxResizeHeight="200dp">
</appwidget-provider>
O snippet de código anterior significa o seguinte:
- O
smallView
oferece suporte a 160 dp (minResizeWidth
) × 110 dp (minResizeHeight
) a 160 dp × 199 dp (próximo ponto de corte: 1 dp). - O
tallView
oferece suporte a 160 dp × 200 dp a 214 dp (próximo ponto de corte: 1) × 200 dp. A
wideView
oferece suporte a 215 dp × 110 dp (minResizeHeight
) a 250 dp (maxResizeWidth
) × 200 dp (maxResizeHeight
).
Seu widget precisa ser compatível com o intervalo de tamanho de minResizeWidth
× minResizeHeight
a maxResizeWidth
× maxResizeHeight
. Dentro desse intervalo,
é possível decidir o ponto de corte para mudar o layout.
![Exemplo de layout responsivo](https://developer.android.google.cn/static/images/appwidgets/size-range.gif?authuser=8&hl=pt-br)
Fornecer layouts exatos
Se não for viável usar um pequeno conjunto de layouts responsivos, é possível fornecer layouts diferentes de acordo com os tamanhos de exibição do widget. Normalmente, há dois tamanhos para smartphones (modo retrato e paisagem) e quatro para dispositivos dobráveis.
Para implementar essa solução, o app precisa realizar as seguintes etapas:
Sobrecarregue
AppWidgetProvider.onAppWidgetOptionsChanged()
, que é chamado quando o conjunto de tamanhos muda.Chame
AppWidgetManager.getAppWidgetOptions()
, que retorna umBundle
contendo os tamanhos.Acesse a chave
AppWidgetManager.OPTION_APPWIDGET_SIZES
doBundle
.
O exemplo de código a seguir mostra como fornecer layouts exatos.
Kotlin
override fun onAppWidgetOptionsChanged( context: Context, appWidgetManager: AppWidgetManager, id: Int, newOptions: Bundle? ) { super.onAppWidgetOptionsChanged(context, appWidgetManager, id, newOptions) // Get the new sizes. val sizes = newOptions?.getParcelableArrayList<SizeF>( AppWidgetManager.OPTION_APPWIDGET_SIZES ) // Check that the list of sizes is provided by the launcher. if (sizes.isNullOrEmpty()) { return } // Map the sizes to the RemoteViews that you want. val remoteViews = RemoteViews(sizes.associateWith(::createRemoteViews)) appWidgetManager.updateAppWidget(id, remoteViews) } // Create the RemoteViews for the given size. private fun createRemoteViews(size: SizeF): RemoteViews { }
Java
@Override public void onAppWidgetOptionsChanged( Context context, AppWidgetManager appWidgetManager, int appWidgetId, Bundle newOptions) { super.onAppWidgetOptionsChanged(context, appWidgetManager, appWidgetId, newOptions); // Get the new sizes. ArrayList<SizeF> sizes = newOptions.getParcelableArrayList(AppWidgetManager.OPTION_APPWIDGET_SIZES); // Check that the list of sizes is provided by the launcher. if (sizes == null || sizes.isEmpty()) { return; } // Map the sizes to the RemoteViews that you want. Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>(); for (SizeF size : sizes) { viewMapping.put(size, createRemoteViews(size)); } RemoteViews remoteViews = new RemoteViews(viewMapping); appWidgetManager.updateAppWidget(id, remoteViews); } // Create the RemoteViews for the given size. private RemoteViews createRemoteViews(SizeF size) { }
Determinar o tamanho do widget
Cada widget precisa definir uma targetCellWidth
e um targetCellHeight
para dispositivos
com o Android 12 ou versões mais recentes (ou minWidth
e minHeight
para todas
as versões do Android), indicando a quantidade mínima de espaço que ele consome
por padrão. No entanto, quando os usuários adicionam um widget à tela inicial, ele geralmente
ocupa mais do que a largura e a altura mínimas especificadas.
As telas iniciais do Android oferecem aos usuários uma grade de espaços disponíveis em que podem
colocar widgets e ícones. Essa grade pode variar de acordo com o dispositivo. Por exemplo, muitos
celulares oferecem uma grade 5x4, e os tablets podem oferecer uma grade maior. Quando o widget
é adicionado, ele é esticado para ocupar o número mínimo de células,
horizontal e vertical, necessário para atender às restrições para
targetCellWidth
e targetCellHeight
em dispositivos com o
Android 12 ou versões mais recentes, ou restrições minWidth
e minHeight
em
dispositivos com o Android 11 (nível 30 da API) ou anterior.
A largura e a altura de uma célula e o tamanho das margens automáticas aplicadas aos widgets podem variar de acordo com o dispositivo. Use a tabela a seguir para estimar aproximadamente as dimensões mínimas do widget em um dispositivo comum com grade 5x4, considerando o número desejado de células de grade ocupadas:
Número de células (largura x altura) | Tamanho disponível em modo retrato (dp) | Tamanho disponível no modo paisagem (dp) |
---|---|---|
1x1 | 57x102dp | 127x51dp |
2x1 | 130x102dp | 269x51dp |
3x1 | 203x102dp | 412x51dp |
4x1 | 276x102dp | 554x51dp |
5x1 | 349x102dp | 697x51dp |
5x2 | 349x220dp | 697x117dp |
5x3 | 349x337dp | 697x184dp |
5x4 | 349x455dp | 697x250dp |
… | … | … |
n x m | (73n - 16) x (118m - 16) | (142n - 15) x (66m - 15) |
Use os tamanhos de célula do modo retrato para informar os valores fornecidos para
os atributos minWidth
, minResizeWidth
e maxResizeWidth
. Da mesma forma,
use os tamanhos de célula no modo paisagem para informar os valores fornecidos
para os atributos minHeight
, minResizeHeight
e maxResizeHeight
.
O motivo é que a largura da célula normalmente é menor no modo retrato do que no modo paisagem. Da mesma forma, a altura da célula normalmente é menor no modo paisagem do que no modo retrato.
Por exemplo, se você quiser que a largura do widget seja redimensionável para uma célula em
um Google Pixel 4, defina o minResizeWidth
como no máximo 56 dp
para garantir que o valor do atributo minResizeWidth
seja menor
que 57 dp, já que uma célula tem pelo menos 57 dp de largura no modo retrato.
Da mesma forma, se você quiser que a altura do widget seja redimensionável em uma célula no
mesmo dispositivo, defina o minResizeHeight
como no máximo 50 dp para garantir
que o valor do atributo minResizeHeight
seja menor que
51 dp, porque uma célula tem pelo menos 51 dp de altura no modo paisagem.
Cada widget é redimensionável dentro das faixas de tamanho entre os atributos
minResizeWidth
/minResizeHeight
e maxResizeWidth
/maxResizeHeight
, o que significa que ele precisa se adaptar a qualquer intervalo de tamanho entre eles.
Por exemplo, para definir o tamanho padrão do widget na posição, você pode definir os seguintes atributos:
<appwidget-provider
android:targetCellWidth="3"
android:targetCellHeight="2"
android:minWidth="180dp"
android:minHeight="110dp">
</appwidget-provider>
Isso significa que o tamanho padrão do widget é de células 3x2, conforme especificado pelos atributos
targetCellWidth
e targetCellHeight
, ou 180×110 dp, conforme
especificado por minWidth
e minHeight
para dispositivos com
Android 11 ou versões anteriores. No último caso, o tamanho nas células pode
variar dependendo do dispositivo.
Além disso, para definir as faixas de tamanho compatíveis com o widget, defina os seguintes atributos:
<appwidget-provider
android:minResizeWidth="180dp"
android:minResizeHeight="110dp"
android:maxResizeWidth="530dp"
android:maxResizeHeight="450dp">
</appwidget-provider>
Conforme especificado pelos atributos anteriores, a largura do widget é redimensionável de 180 dp para 530 dp, e a altura dele é redimensionável de 110 dp para 450 dp. O widget é redimensionável de células 3 x 2 para 5 x 2, desde que as seguintes condições estejam presentes:
- O dispositivo tem a grade 5x4.
- O mapeamento entre o número de células e o tamanho disponível em dps segue a tabela que mostra a estimativa de dimensões mínimas nesta página.
- O widget se adapta a esse intervalo de tamanho.
Kotlin
val smallView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_small) val mediumView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_medium) val largeView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_large) val viewMapping: Map<SizeF, RemoteViews> = mapOf( SizeF(180f, 110f) to smallView, SizeF(270f, 110f) to mediumView, SizeF(270f, 280f) to largeView ) appWidgetManager.updateAppWidget(appWidgetId, RemoteViews(viewMapping))
Java
RemoteViews smallView = new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_small); RemoteViews mediumView = new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_medium); RemoteViews largeView = new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_large); Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>(); viewMapping.put(new SizeF(180f, 110f), smallView); viewMapping.put(new SizeF(270f, 110f), mediumView); viewMapping.put(new SizeF(270f, 280f), largeView); RemoteViews remoteViews = new RemoteViews(viewMapping); appWidgetManager.updateAppWidget(id, remoteViews);
Suponha que o widget use os layouts responsivos definidos nos snippets
de código anteriores. Isso significa que o layout especificado como
R.layout.widget_weather_forecast_small
é usado de 180 dp (minResizeWidth
) x
110 dp (minResizeHeight
) a 269 x 279 dp (próximos pontos de corte - 1). Da mesma forma,
R.layout.widget_weather_forecast_medium
é usado de 270 x 110 dp a 270 x 279 dp,
e R.layout.widget_weather_forecast_large
é usado de 270 x 280 dp a
530 dp (maxResizeWidth
) x 450 dp (maxResizeHeight
).
À medida que o usuário redimensiona o widget, a aparência dele muda para se adaptar a cada tamanho nas células, conforme mostrado nos exemplos abaixo.
![Exemplo de widget de previsão do tempo no menor tamanho de grade 3x2. A interface mostra o nome do local (Tóquio), a temperatura (14 °) e o símbolo indicando que o clima está parcialmente nublado.](https://developer.android.google.cn/static/images/appwidgets/weather-size-3x2.png?authuser=8&hl=pt-br)
R.layout.widget_weather_forecast_small
.![Exemplo de widget de previsão do tempo em tamanho médio 4 x 2. Redimensionar o widget dessa maneira se baseia em toda a interface do tamanho de widget anterior e adiciona o rótulo "Predominantemente nublado" e uma previsão de temperaturas das 16h às 19h.](https://developer.android.google.cn/static/images/appwidgets/weather-size-4x2.png?authuser=8&hl=pt-br)
R.layout.widget_weather_forecast_medium
.![Exemplo de widget de previsão do tempo em tamanho médio de 5 x 2. Redimensionar o widget dessa maneira resulta na mesma IU que o tamanho anterior, mas é esticado em um comprimento de célula para ocupar mais espaço horizontal.](https://developer.android.google.cn/static/images/appwidgets/weather-size-5x2.png?authuser=8&hl=pt-br)
R.layout.widget_weather_forecast_medium
.![Exemplo de widget de previsão do tempo em um tamanho "grande" 5x3. Redimensionar o widget dessa maneira se baseia em toda a IU dos tamanhos de widget anteriores e adiciona uma visualização dentro do widget com uma previsão do tempo nas terças e quartas. Símbolos que indicam clima ensolarado ou chuvoso e temperaturas máximas e mínimas para cada dia.](https://developer.android.google.cn/static/images/appwidgets/weather-size-5x3.png?authuser=8&hl=pt-br)
R.layout.widget_weather_forecast_large
.![Exemplo de widget de previsão do tempo em um tamanho "grande" 5x4. Redimensionar o widget dessa maneira se baseia em toda a interface dos tamanhos de widget anteriores e adiciona quinta-feira e sexta-feira e os símbolos correspondentes que indicam o tipo de clima, bem como as temperaturas máxima e baixa de cada dia.](https://developer.android.google.cn/static/images/appwidgets/weather-size-5x4.png?authuser=8&hl=pt-br)
R.layout.widget_weather_forecast_large
.