Cómo compilar una IU con Glance

En esta página, se describe cómo controlar los tamaños y proporcionar diseños flexibles y responsivos con Crashlytics.

Usa Box, Column y Row

Shortcuts tiene tres diseños principales componibles:

• Box: Coloca elementos sobre otro. Se traduce como RelativeLayout.

• Column: Ubica los elementos uno tras otro en el eje vertical. Se traduce a un LinearLayout con orientación vertical.

• Row: Ubica los elementos uno tras otro en el eje horizontal. Se traduce a un LinearLayout con orientación horizontal.

Cada uno de estos elementos componibles te permite definir las alineaciones verticales y horizontales de su contenido y las restricciones de ancho, altura, peso o padding usando modificadores. Además, cada elemento secundario puede definir su modificador para cambiar el espacio y la posición dentro del elemento superior.

En el siguiente ejemplo, se muestra cómo crear un Row que distribuya de manera uniforme sus elementos secundarios de forma horizontal, como se muestra en la Figura 1:

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

El Row completa el ancho máximo disponible y, como cada elemento secundario tiene el mismo peso, comparten el espacio disponible de manera uniforme. Puedes definir diferentes grosores, tamaños, paddings o alineaciones para adaptar los diseños a tus necesidades.

Cómo usar diseños desplazables

Otra forma de ofrecer contenido responsivo es hacer que se pueda desplazar. Esto es posible con el elemento componible LazyColumn. Ese elemento te permite definir un conjunto de elementos que se mostrarán dentro de un contenedor desplazable en el widget de la app.

Los siguientes fragmentos muestran diferentes formas de definir elementos dentro de LazyColumn.

Puedes proporcionar la cantidad de elementos:

// 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

Proporciona elementos individuales:

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

Proporciona una lista o un array de elementos:

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

También puedes usar una combinación de los ejemplos 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

Ten en cuenta que el fragmento anterior no especifica el itemId. Especificar itemId ayuda a mejorar el rendimiento y mantener la posición de desplazamiento a través de las actualizaciones de la lista y de appWidget a partir de Android 12 (por ejemplo, al agregar o quitar elementos de la lista). En el siguiente ejemplo, se muestra cómo especificar un itemId:

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

Define el SizeMode

Los tamaños de AppWidget pueden diferir según el dispositivo, la elección del usuario o el selector, por lo que es importante proporcionar diseños flexibles, como se describe en la página Cómo proporcionar diseños de widgets flexibles. Vistazo simplifica esto con la definición de SizeMode y el valor LocalSize. En las siguientes secciones, se describen los tres modos.

SizeMode.Single

SizeMode.Single es el modo predeterminado. Indica que solo se proporciona un tipo de contenido; es decir, incluso si cambia el tamaño disponible de AppWidget, el tamaño del contenido no se modifica.

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

Cuando uses este modo, asegúrate de lo siguiente:

• Los valores de metadatos de tamaño mínimo y máximo se definen correctamente en función del tamaño del contenido.
• El contenido es lo suficientemente flexible dentro del rango de tamaño esperado.

En general, debes usar este modo en los siguientes casos:

a) AppWidget tiene un tamaño fijo o b) no cambia su contenido cuando se cambia su tamaño.

SizeMode.Responsive

Este modo es el equivalente a proporcionar diseños responsivos, que permite que GlanceAppWidget defina un conjunto de diseños responsivos delimitados por tamaños específicos. Para cada tamaño definido, el contenido se crea y se asigna al tamaño específico cuando se crea o actualiza AppWidget. Luego, el sistema selecciona el mejor ajuste según el tamaño disponible.

Por ejemplo, en nuestro AppWidget de destino, puedes definir tres tamaños y su contenido:

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

En el ejemplo anterior, se llama al método provideContent tres veces y se asigna al tamaño definido.

• En la primera llamada, el tamaño se evalúa como 100x100. El contenido no incluye el botón adicional ni los textos inferior y superior.
• En la segunda llamada, el tamaño se evalúa como 250x100. El contenido incluye el botón adicional, pero no los textos inferior y superior.
• En la tercera llamada, el tamaño se evalúa como 250x250. El contenido incluye el botón adicional y ambos textos.

SizeMode.Responsive es una combinación de los otros dos modos y te permite definir contenido responsivo dentro de límites predefinidos. En general, este modo funciona mejor y permite transiciones más fluidas cuando se cambia el tamaño de AppWidget.

En la siguiente tabla, se muestra el valor del tamaño según el SizeMode y el AppWidget disponible:

Tamaño disponible	105 × 110	203 × 112	72 × 72	203 × 150
SizeMode.Single	110 × 110	110 × 110	110 × 110	110 × 110
SizeMode.Exact	105 × 110	203 × 112	72 × 72	203 × 150
SizeMode.Responsive	80 x 100	80 x 100	80 x 100	150 x 120
* Los valores exactos son solo para fines de demostración.

SizeMode.Exact

SizeMode.Exact es el equivalente a proporcionar diseños exactos, que solicita el contenido GlanceAppWidget cada vez que cambia el tamaño de AppWidget disponible (por ejemplo, cuando el usuario cambia el tamaño de AppWidget en la pantalla principal).

Por ejemplo, en el widget de destino, se puede agregar un botón adicional si el ancho disponible es mayor que un valor determinado.

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

Este modo proporciona más flexibilidad que los otros, pero conlleva algunas advertencias:

• El elemento AppWidget debe volver a crearse por completo cada vez que cambie el tamaño. Esto puede generar problemas de rendimiento y saltos de la IU cuando el contenido es complejo.
• El tamaño disponible puede variar según la implementación del selector. Por ejemplo, si el selector no proporciona la lista de tamaños, se utiliza el tamaño mínimo posible.
• En dispositivos con versiones anteriores a Android 12, es posible que la lógica de cálculo de tamaño no funcione en todas las situaciones.

En general, debes usar este modo si no se puede usar SizeMode.Responsive (es decir, no es posible usar un conjunto pequeño de diseños responsivos).

Accede a recursos

Usa LocalContext.current para acceder a cualquier recurso de Android, como se muestra en el siguiente ejemplo:

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

Te recomendamos que proporciones los IDs de recursos directamente para reducir el tamaño del objeto RemoteViews final y habilitar los recursos dinámicos, como los colores dinámicos.

Los elementos componibles y los métodos aceptan recursos mediante un "proveedor", como ImageProvider, o con un método de sobrecarga como GlanceModifier.background(R.color.blue). Por ejemplo:

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

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

Cómo agregar botones compuestos

Los botones compuestos se introdujeron en Android 12. Vistazo admite la retrocompatibilidad con los siguientes tipos de botones compuestos:

• Switch
• CheckBox
• RadioButton

Cada uno de estos botones compuestos muestra una vista en la que se puede hacer clic que representa el estado "marcado".

var isApplesChecked by remember { mutableStateOf(false) }
var isEnabledSwitched by remember { mutableStateOf(false) }
var isRadioChecked by remember { mutableStateOf(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

Cuando cambia el estado, se activa la lambda proporcionada. Puedes almacenar el estado de verificación, como se muestra en el siguiente ejemplo:

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

También puedes proporcionar el atributo colors a CheckBox, Switch y RadioButton para personalizar sus colores:

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