En esta página, se describe cómo controlar los tamaños y proporcionar diseños flexibles y responsivos con Glance con los componentes existentes de Glance
Usa Box
, Column
y Row
Vistazo tiene tres diseños principales componibles:
Box
: Coloca los elementos encima de otros. Se traduce en unRelativeLayout
.Column
: Ubica los elementos uno detrás de otro en el eje vertical. Se traduce en unLinearLayout
con orientación vertical.Row
: Ubica los elementos uno detrás de otro en el eje horizontal. Se traduce en un objetoLinearLayout
con orientación horizontal.
Vistazo compatible con objetos Scaffold
. Coloca los elementos Column
, Row
y Box
componibles dentro de un objeto Scaffold
determinado.
Cada uno de estos elementos componibles te permite definir los alineamientos verticales y horizontales de su contenido, así como las restricciones de ancho, altura, peso o padding mediante 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 sus elementos secundarios horizontalmente de manera uniforme, como se ve en la Figura 1:
Row(modifier = GlanceModifier.fillMaxWidth().padding(16.dp)) { val modifier = GlanceModifier.defaultWeight() Text("first", modifier) Text("second", modifier) Text("third", modifier) }
Row
ocupa el ancho máximo disponible y, debido a que cada elemento secundario tiene el mismo peso, comparten de manera uniforme el espacio disponible. Puedes definir diferentes pesos, tamaños, paddings o alineaciones para adaptar los diseños a tus necesidades.
Cómo usar diseños desplazables
Otra forma de proporcionar contenido responsivo es hacerlo que se pueda desplazar. Esto es posible con el elemento LazyColumn
componible. Ese elemento te permite definir un conjunto de elementos que se mostrarán dentro de un contenedor desplazable en el widget de la app.
En los siguientes fragmentos, se muestran diferentes formas de definir elementos dentro de LazyColumn
.
Puedes proporcionar la cantidad de elementos de las siguientes maneras:
// Remember to import Glance Composables // import androidx.glance.appwidget.layout.LazyColumn LazyColumn { items(10) { index: Int -> Text( text = "Item $index", modifier = GlanceModifier.fillMaxWidth() ) } }
Proporciona elementos individuales:
LazyColumn { item { Text("First Item") } item { Text("Second Item") } }
Proporciona una lista o un array de elementos:
LazyColumn { items(peopleNameList) { name -> Text(name) } }
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") } }
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 en las actualizaciones de la lista y appWidget
a partir de Android 12 (por ejemplo, cuando se agregan o quitan 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) }
Define el SizeMode
Los tamaños de AppWidget
pueden variar 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. La vista rápida 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, aunque cambie el tamaño disponible de AppWidget
, no se modificará.
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 // ... } }
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) la AppWidget
tiene un tamaño fijo o b) no cambia su contenido cuando se le cambia el tamaño.
SizeMode.Responsive
Este modo es el equivalente a proporcionar diseños responsivos, que permite que el GlanceAppWidget
defina un conjunto de diseños responsivos delimitados por tamaños específicos. Para cada tamaño definido, se crea el contenido y se asigna al tamaño específico cuando se crea o actualiza el AppWidget
. Luego, el sistema selecciona el mejor ajuste en función del 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") } } } }
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 de la parte superior y la inferior. - En la segunda llamada, el tamaño se evalúa como
250x100
. El contenido incluye el botón adicional, pero no los textos de la parte superior y la inferior. - 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 los límites predefinidos. En general, este modo tiene un mejor rendimiento 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 tamaño disponible SizeMode
y AppWidget
:
Tamaño disponible | 105 x 110 | 203 x 112 | 72 x 72 | 203 × 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 × 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") } } } } }
Este modo proporciona más flexibilidad que los otros, pero tiene algunas advertencias:
- El elemento
AppWidget
debe volver a crearse por completo cada vez que cambie el tamaño. lo que puede generar problemas de rendimiento y saltos en 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 usa 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 pequeño conjunto 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)
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 que usan un "proveedor", como ImageProvider
, o que usan 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", )
Cómo procesar texto
Glance 1.1.0 incluye una API para configurar tus estilos de texto. Establece estilos de texto con los atributos fontSize
, fontWeight
o fontFamily
de la clase TextStyle.
fontFamily
admite todas las fuentes del sistema, como se muestra en el siguiente ejemplo, pero no las fuentes personalizadas en las apps:
Text(
style = TextStyle(
fontWeight = FontWeight.Bold,
fontSize = 18.sp,
fontFamily = FontFamily.Monospace
),
text = "Example Text"
)
Cómo agregar botones compuestos
Los botones compuestos se introdujeron en Android 12. Glance admite la retrocompatibilidad para los siguientes tipos de botones compuestos:
Cada uno de los 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" )
Cuando cambia el estado, se activa la expresión 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) } ) } }
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) ), )
Componentes adicionales
Glance 1.1.0 incluye la versión de componentes adicionales, como se describe en la siguiente tabla:
Nombre | Imagen | Vínculo de referencia | Notas adicionales |
---|---|---|---|
Botón relleno | Componente | ||
Botones con contorno | Componente | ||
Botones de íconos | Componente | Principal / secundario / Solo icono | |
Barra de título | Componente | ||
Scaffold | El andamiaje y la barra de título están en la misma demostración. |
Para obtener más información sobre los detalles del diseño, consulta los diseños de componentes en este kit de diseño en Figma.