Criar uma interface com o Glance

Esta página descreve como processar tamanhos e fornecer layouts flexíveis e responsivos com o Glance, usando componentes atuais do Glance.

Usar Box, Column e Row

O Glance tem três layouts combináveis principais:

• Box: coloca elementos um em cima do outro. Ele é traduzido para um RelativeLayout.

• Column: coloca elementos um após o outro no eixo vertical. Ele é traduzido para um LinearLayout com orientação vertical.

• Row: coloca elementos um após o outro no eixo horizontal. Ele é traduzido para um LinearLayout com orientação horizontal.

O Glance oferece suporte a Scaffold objetos. Coloque os elementos combináveis Column, Row e Box em um determinado objeto Scaffold.

Figura 1. Exemplos de layouts com Column, Row e Box.

Ponto-chave: o Glance oferece uma abordagem moderna para criar widgets de apps usando o Compose, mas é restrito pelas limitações de AppWidgets e RemoteViews. Portanto, o Glance usa elementos combináveis diferentes da interface do Jetpack Compose.

Cada um desses elementos combináveis permite definir os alinhamentos vertical e horizontal do conteúdo e as restrições de largura, altura, peso ou preenchimento usando modificadores. Além disso, cada filho pode definir o modificador para mudar o espaço e o posicionamento dentro do pai.

O exemplo a seguir mostra como criar uma Row que distribui os filhos horizontalmente de maneira uniforme, conforme mostrado na Figura 1:

Row(modifier = GlanceModifier.fillMaxWidth().padding(16.dp)) {
    val modifier = GlanceModifier.defaultWeight()
    Text("first", modifier)
    Text("second", modifier)
    Text("third", modifier)
}
GlanceSnippets.kt

A Row preenche a largura máxima disponível e, como cada filho tem o mesmo peso, eles compartilham o espaço disponível de maneira uniforme. É possível definir pesos, tamanhos, preenchimentos ou alinhamentos diferentes para adaptar os layouts às suas necessidades.

Observação: o Glance traduz os elementos combináveis em Views, usando os modificadores e parâmetros definidos para criar a visualização subjacente. Assim, os mesmos conceitos de visualização do Android (como pesos) são aplicados ao criar determinados elementos combináveis com o Glance.

Usar layouts roláveis

Outra maneira de fornecer conteúdo responsivo é torná-lo rolável. Isso é possível com o elemento combinável LazyColumn. Esse elemento combinável permite definir um conjunto de itens a serem exibidos em um contêiner rolável no widget do app.

Os snippets a seguir mostram diferentes maneiras de definir itens dentro do LazyColumn.

É possível fornecer o número de itens:

// Remember to import Glance Composables
// import androidx.glance.appwidget.layout.LazyColumn

LazyColumn {
    items(10) { index: Int ->
        Text(
            text = "Item $index",
            modifier = GlanceModifier.fillMaxWidth()
        )
    }
}
GlanceSnippets.kt

Fornecer itens individuais:

LazyColumn {
    item {
        Text("First Item")
    }
    item {
        Text("Second Item")
    }
}
GlanceSnippets.kt

Fornecer uma lista ou matriz de itens:

LazyColumn {
    items(peopleNameList) { name ->
        Text(name)
    }
}
GlanceSnippets.kt

Também é possível usar uma combinação dos exemplos anteriores:

LazyColumn {
    item {
        Text("Names:")
    }
    items(peopleNameList) { name ->
        Text(name)
    }

    // or in case you need the index:
    itemsIndexed(peopleNameList) { index, person ->
        Text("$person at index $index")
    }
}
GlanceSnippets.kt

O snippet anterior não especifica o itemId. Especificar o itemId ajuda a melhorar o desempenho e manter a posição de rolagem nas atualizações de lista e appWidget do Android 12 em diante (por exemplo, ao adicionar ou remover itens da lista). O exemplo a seguir mostra como especificar um itemId:

items(items = peopleList, itemId = { person -> person.id.hashCode().toLong() }) { person ->
    Text(person.name)
}
GlanceSnippets.kt

Observação: o Glance traduz um LazyColumn em um ListView com a tradução dos itens fornecidos. Assim, as mesmas limitações e restrições das coleções RemoteViews são aplicadas. Essas limitações não se aplicam se você usar a rolagem instantânea, que usa o Remote Compose em vez de RemoteViews.

Rolagem instantânea

A rolagem instantânea é uma animação que permite que o conteúdo rolável seja ajustado à parte de cima do contêiner de widget.

Vídeo 1. A esquerda mostra um item de lista que não se encaixa no lugar durante a rolagem, e a direita se encaixa.

Para implementar a rolagem instantânea, verifique se você atende às seguintes condições:

• Atualize a dependência do Glance para 1.3.0-alpha02 ou mais recente.
• Defina o compileSdk como 37 ou mais recente, já que a rolagem instantânea é compatível com dispositivos que executam o Android 17 e versões mais recentes.
• Configure o LazyColumn com VerticalScrollMode. Se o dispositivo oferecer suporte à rolagem instantânea, use SnapScrollMatchHeight. Caso contrário, use Normal.

Observação: SnapScrollMatchHeight foi projetado para quando cada elemento filho corresponde à altura do contêiner pai, como em imagens de sangria total. Para garantir que a altura transmitida de LocalSize.current para SnapScrollMatchHeight reflita com precisão o espaço disponível na tela inicial do usuário, use SizeMode.Exact. Caso contrário, LocalSize.current vai usar as dimensões mínimas definidas no XML de metadados do AppWidget. Para mais informações, consulte Definir o SizeMode.

Se você estiver usando a rolagem instantânea com imagens, consulte o layout canônico de imagem de sangria total.

@Composable
fun SnapScrollLayout() {
    val height = LocalSize.current.height
    val items = listOf(
        ColorItem(Color.Red, "Red"),
        ColorItem(Color.Yellow, "Yellow"),
        ColorItem(Color.Blue, "Blue")
    )

    val scrollMode = if (Build.VERSION.SDK_INT >= 37) {
        VerticalScrollMode.SnapScrollMatchHeight(height)
    } else {
        VerticalScrollMode.Normal
    }

    LazyColumn(
        verticalScrollMode = scrollMode
    ) {
        items(items) { item ->
            ColorCard(item, height)
        }
    }
}

@Composable
private fun ColorCard(item: ColorItem, height: Dp) {
    Box(
        modifier = GlanceModifier
            .background(item.color)
            .fillMaxWidth()
            .height(height),
        contentAlignment = Alignment.Center
    ) {
        Text(
            text = item.name,
            modifier = GlanceModifier.background(Color.White)
        )
    }
}
GlanceSnippets.kt

Definir o SizeMode

Os tamanhos de AppWidget podem variar dependendo do dispositivo, da escolha do usuário ou do inicializador, por isso, é importante fornecer layouts flexíveis, conforme descrito na página Fornecer layouts de widget flexíveis. O Glance simplifica isso com a definição SizeMode e o valor LocalSize. As seções a seguir descrevem os três modos.

SizeMode.Single

SizeMode.Single é o modo padrão. Ele indica que apenas um tipo de conteúdo é fornecido. Ou seja, mesmo que o tamanho disponível do AppWidget mude, o tamanho do conteúdo não será alterado.

class MyAppWidget : GlanceAppWidget() {

    override val sizeMode = SizeMode.Single

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // ...

        provideContent {
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        // Size will be the minimum size or resizable
        // size defined in the App Widget metadata
        val size = LocalSize.current
        // ...
    }
}
GlanceSnippets.kt

Ao usar esse modo, verifique se:

• Os valores de metadados de tamanho mínimo e máximo estão definidos corretamente com base no tamanho do conteúdo.
• O conteúdo é flexível o suficiente dentro do intervalo de tamanho esperado.

Em geral, use esse modo quando:

a) o AppWidget tem um tamanho fixo ou b) não muda o conteúdo quando redimensionado.

SizeMode.Responsive

Esse modo é o equivalente a fornecer layouts responsivos, o que permite que o GlanceAppWidget defina um conjunto de layouts responsivos limitados por tamanhos específicos. Para cada tamanho definido, o conteúdo é criado e mapeado para o tamanho específico quando o AppWidget é criado ou atualizado. Em seguida, o sistema seleciona o mais adequado com base no tamanho disponível.

Observação: o tamanho mais adequado é um dos DpSize fornecidos que se encaixa na caixa delimitadora disponível com distorção mínima. Se nenhum se encaixar, o menor será usado.

Por exemplo, no nosso destino AppWidget, é possível definir três tamanhos e o conteúdo dele:

class MyAppWidget : GlanceAppWidget() {

    companion object {
        private val SMALL_SQUARE = DpSize(100.dp, 100.dp)
        private val HORIZONTAL_RECTANGLE = DpSize(250.dp, 100.dp)
        private val BIG_SQUARE = DpSize(250.dp, 250.dp)
    }

    override val sizeMode = SizeMode.Responsive(
        setOf(
            SMALL_SQUARE,
            HORIZONTAL_RECTANGLE,
            BIG_SQUARE
        )
    )

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // ...

        provideContent {
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        // Size will be one of the sizes defined above.
        val size = LocalSize.current
        Column {
            if (size.height >= BIG_SQUARE.height) {
                Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            }
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button()
                Button()
                if (size.width >= HORIZONTAL_RECTANGLE.width) {
                    Button("School")
                }
            }
            if (size.height >= BIG_SQUARE.height) {
                Text(text = "provided by X")
            }
        }
    }
}
GlanceSnippets.kt

No exemplo anterior, o método provideContent é chamado três vezes e mapeado para o tamanho definido.

• Na primeira chamada, o tamanho é avaliado como 100x100. O conteúdo não inclui o botão extra nem os textos de cima e de baixo.
• Na segunda chamada, o tamanho é avaliado como 250x100. O conteúdo inclui o botão extra, mas não os textos de cima e de baixo.
• Na terceira chamada, o tamanho é avaliado como 250x250. O conteúdo inclui o botão extra e os dois textos.

SizeMode.Responsive é uma combinação dos outros dois modos e permite definir conteúdo responsivo dentro de limites predefinidos. Em geral, esse modo tem um desempenho melhor e permite transições mais suaves quando o AppWidget é redimensionado.

Observação: os layouts responsivos foram introduzidos no Android 12. Antes do Android 12, o elemento combinável era chamado para cada tamanho em que o widget do app podia ser exibido (semelhante a SizeMode.Exact). Para cada tamanho, a melhor visualização é escolhida, que é a maior que se encaixa no espaço disponível ou a menor, se nenhuma se encaixar.

A tabela a seguir mostra o valor do tamanho, dependendo do SizeMode e do tamanho disponível do AppWidget:

Tamanho disponível	105 x 110	203 x 112	72 x 72	203 x 150
SizeMode.Single	110 x 110	110 x 110	110 x 110	110 x 110
SizeMode.Exact	105 x 110	203 x 112	72 x 72	203 x 150
SizeMode.Responsive	80 x 100	80 x 100	80 x 100	150 x 120
* Os valores exatos são apenas para fins de demonstração.

SizeMode.Exact

SizeMode.Exact é o equivalente a fornecer layouts exatos, que solicita o conteúdo GlanceAppWidget sempre que o tamanho disponível do AppWidget muda (por exemplo, quando o usuário redimensiona o AppWidget na tela inicial).

Por exemplo, no widget de destino, um botão extra pode ser adicionado se a largura disponível for maior que um determinado valor.

class MyAppWidget : GlanceAppWidget() {

    override val sizeMode = SizeMode.Exact

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // ...

        provideContent {
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        // Size will be the size of the AppWidget
        val size = LocalSize.current
        Column {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button()
                Button()
                if (size.width > 250.dp) {
                    Button("School")
                }
            }
        }
    }
}
GlanceSnippets.kt

Esse modo oferece mais flexibilidade do que os outros, mas tem algumas ressalvas:

• O AppWidget precisa ser recriado completamente sempre que o tamanho mudar. Isso pode causar problemas de desempenho e saltos na interface quando o conteúdo é complexo.
• O tamanho disponível pode variar dependendo da implementação do inicializador. Por exemplo, se o inicializador não fornecer a lista de tamanhos, o tamanho mínimo possível será usado.
• Em dispositivos anteriores ao Android 12, a lógica de cálculo de tamanho pode não funcionar em todas as situações.

Em geral, use esse modo se SizeMode.Responsive não puder ser usado (ou seja, um pequeno conjunto de layouts responsivos não é viável).

Acessar recursos

Use LocalContext.current para acessar qualquer recurso do Android, conforme mostrado no exemplo a seguir:

LocalContext.current.getString(R.string.glance_title)
GlanceSnippets.kt

Recomendamos fornecer IDs de recursos diretamente para reduzir o tamanho do objeto final RemoteViews e ativar recursos dinâmicos, como cores dinâmicas.

Os elementos combináveis e métodos aceitam recursos usando um "provedor", como ImageProvider, ou usando um método de sobrecarga como GlanceModifier.background(R.color.blue). Por exemplo:

Column(
    modifier = GlanceModifier.background(R.color.default_widget_background)
) { /**...*/ }

Image(
    provider = ImageProvider(R.drawable.ic_logo),
    contentDescription = "My image",
)
GlanceSnippets.kt

Processar texto

O Glance 1.1.0 inclui uma API para definir estilos de texto. Defina estilos de texto usando os atributos fontSize, fontWeight ou fontFamily da classe TextStyle.

fontFamily oferece suporte a todas as fontes do sistema, conforme mostrado no exemplo a seguir, mas as fontes personalizadas em apps não são aceitas:

Text(
    style = TextStyle(
        fontWeight = FontWeight.Bold,
        fontSize = 18.sp,
        fontFamily = FontFamily.Monospace
    ),
    text = "Example Text"
)

Adicionar botões compostos

Os botões compostos foram introduzidos no Android 12. O Glance oferece suporte à compatibilidade com versões anteriores para os seguintes tipos de botões compostos:

• Switch
• CheckBox
• RadioButton

Esses botões compostos mostram uma visualização clicável que representa o estado "marcado".

var isApplesChecked by remember { mutableStateOf(false) }
var isEnabledSwitched by remember { mutableStateOf(false) }
var isRadioChecked by remember { mutableIntStateOf(0) }

CheckBox(
    checked = isApplesChecked,
    onCheckedChange = { isApplesChecked = !isApplesChecked },
    text = "Apples"
)

Switch(
    checked = isEnabledSwitched,
    onCheckedChange = { isEnabledSwitched = !isEnabledSwitched },
    text = "Enabled"
)

RadioButton(
    checked = isRadioChecked == 1,
    onClick = { isRadioChecked = 1 },
    text = "Checked"
)
GlanceSnippets.kt

Quando o estado muda, a lambda fornecida é acionada. É possível armazenar o estado marcado, conforme mostrado no exemplo a seguir:

class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        val myRepository = MyRepository.getInstance()

        provideContent {
            val scope = rememberCoroutineScope()

            val saveApple: (Boolean) -> Unit =
                { scope.launch { myRepository.saveApple(it) } }
            MyContent(saveApple)
        }
    }

    @Composable
    private fun MyContent(saveApple: (Boolean) -> Unit) {

        var isAppleChecked by remember { mutableStateOf(false) }

        Button(
            text = "Save",
            onClick = { saveApple(isAppleChecked) }
        )
    }
}
GlanceSnippets.kt

Também é possível fornecer o atributo colors para CheckBox, Switch e RadioButton para personalizar as cores deles:

CheckBox(
    // ...
    colors = CheckboxDefaults.colors(
        checkedColor = ColorProvider(day = colorAccentDay, night = colorAccentNight),
        uncheckedColor = ColorProvider(day = Color.DarkGray, night = Color.LightGray)
    ),
    checked = isChecked,
    onCheckedChange = { isChecked = !isChecked }
)

Switch(
    // ...
    colors = SwitchDefaults.colors(
        checkedThumbColor = ColorProvider(day = Color.Red, night = Color.Cyan),
        uncheckedThumbColor = ColorProvider(day = Color.Green, night = Color.Magenta),
        checkedTrackColor = ColorProvider(day = Color.Blue, night = Color.Yellow),
        uncheckedTrackColor = ColorProvider(day = Color.Magenta, night = Color.Green)
    ),
    checked = isChecked,
    onCheckedChange = { isChecked = !isChecked },
    text = "Enabled"
)

RadioButton(
    // ...
    colors = RadioButtonDefaults.colors(
        checkedColor = ColorProvider(day = Color.Cyan, night = Color.Yellow),
        uncheckedColor = ColorProvider(day = Color.Red, night = Color.Blue)
    ),

)
GlanceSnippets.kt

**Observação**: consulte o exemplo CompoundButtonAppWidget.kt para um exemplo mais detalhado.

Componentes adicionais

O Glance 1.1.0 inclui o lançamento de componentes adicionais, conforme descrito na tabela a seguir:

Nome	Imagem	Link de referência	Outras observações
Botão preenchido		Component
Botões de contorno		Component
Botões de ícone		Component	Principal / Secundário / Somente ícone
Barra de título		Component
Scaffold			Scaffold e barra de título estão na mesma demonstração.

Para mais informações sobre especificidades de design, consulte os designs de componentes neste kit de design no Figma.

Para mais informações sobre layouts canônicos, acesse Layouts de widget canônicos.