本页介绍了如何通过 Glance 处理尺寸以及提供灵活的自适应布局。
使用 Box
、Column
和 Row
Glance 有三个主要的可组合项布局:
Box
:将元素放在另一个元素上。它会转换为RelativeLayout
。Column
:在纵轴上依次放置元素。它会转换为具有垂直方向的LinearLayout
。Row
:在横轴上连续放置元素。它会转换为水平方向的LinearLayout
。
每个可组合项都允许您使用修饰符定义其内容的垂直和水平对齐方式,以及宽度、高度、粗细或内边距约束条件。此外,每个子级都可以定义其修饰符,以更改父级中的空间和位置。
以下示例展示了如何创建可在水平均匀分布其子项的 Row
,如图 1 所示:
Row(modifier = GlanceModifier.fillMaxWidth().padding(16.dp)) { val modifier = GlanceModifier.defaultWeight() Text("first", modifier) Text("second", modifier) Text("third", modifier) }
Row
会填满可用宽度上限,由于每个子级的权重相同,因此它们会平均分配可用空间。您可以定义不同的粗细、尺寸、内边距或对齐方式,以根据需要调整布局。
使用可滚动布局
提供自适应内容的另一种方法是使其可滚动。这可以通过 LazyColumn
可组合项实现。借助此可组合项,您可以定义要在应用 widget 的可滚动容器内显示的一组项。
以下代码段展示了定义 LazyColumn
内各项的不同方法。
您可以提供商品数量:
// Remember to import Glance Composables // import androidx.glance.appwidget.layout.LazyColumn LazyColumn { items(10) { index: Int -> Text( text = "Item $index", modifier = GlanceModifier.fillMaxWidth() ) } }
提供单件商品:
LazyColumn { item { Text("First Item") } item { Text("Second Item") } }
提供项目列表或数组:
LazyColumn { items(peopleNameList) { name -> Text(name) } }
您还可以组合使用上述示例:
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") } }
请注意,前面的代码段没有指定 itemId
。指定 itemId
有助于提升性能,并且从 Android 12 开始,通过列表和 appWidget
更新维护滚动位置(例如,在列表中添加或移除项时)。以下示例展示了如何指定 itemId
:
items(items = peopleList, key = { person -> person.id }) { person -> Text(person.name) }
定义 SizeMode
AppWidget
尺寸可能会因设备、用户选择或启动器而异,因此请务必提供灵活的布局,如提供灵活的 widget 布局页面中所述。Glance 通过 SizeMode
定义和 LocalSize
值简化了这一过程。以下部分介绍了这三种模式。
SizeMode.Single
SizeMode.Single
是默认模式。它表示仅提供一种类型的内容;也就是说,即使 AppWidget
可用大小发生变化,内容大小也不会改变。
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 // ... } }
使用此模式时,请确保:
- 您可以根据内容大小正确定义大小下限和上限元数据值。
- 内容在预期的尺寸范围内足够灵活。
一般来说,您应在以下情况下使用此模式:
a) AppWidget
具有固定大小;b) 在调整大小时,它不会更改其内容。
SizeMode.Responsive
此模式相当于提供自适应布局,可让 GlanceAppWidget
定义一组由特定尺寸限定的自适应布局。对于定义的每个尺寸,系统都会在创建或更新 AppWidget
时创建内容,并将其映射到特定尺寸。然后,系统会根据可用尺寸选择最合适的尺寸。
例如,在我们的目的地 AppWidget
中,您可以定义三种尺寸及其内容:
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") } } } }
在前面的示例中,调用了 provideContent
方法三次,并将其映射到定义的尺寸。
- 在第一次调用中,大小求值为
100x100
。内容不包含额外的按钮,也不包含顶部和底部的文本。 - 在第二次调用中,大小的计算结果为
250x100
。内容包含额外的按钮,但不包含顶部和底部文本。 - 在第三个调用中,大小的计算结果为
250x250
。内容包括额外的按钮和两个文本。
SizeMode.Responsive
是其他两种模式的组合,可让您在预定义的边界内定义自适应内容。通常,在调整 AppWidget
的大小时,此模式可提升效果,并可实现更顺畅的过渡。
下表根据可用的 SizeMode
和 AppWidget
显示了大小的值:
可用尺寸 | 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 |
* 确切值仅用于演示目的。 |
SizeMode.Exact
SizeMode.Exact
相当于提供精确布局,后者会在每次可用的 AppWidget
大小发生变化时(例如,当用户在主屏幕上调整 AppWidget
的大小时)请求 GlanceAppWidget
内容。
例如,在目标 widget 中,如果可用宽度大于特定值,则可以添加一个额外的按钮。
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") } } } } }
这种模式比其他模式更加灵活,但存在一些注意事项:
- 每次大小发生变化时,都必须完全重新创建
AppWidget
。当内容很复杂时,这可能会导致性能问题和界面跳动。 - 可用大小可能因启动器的实现而异。例如,如果启动器未提供大小列表,则使用可能的最小大小。
- 在搭载 Android 12 之前版本的设备中,尺寸计算逻辑可能并非在所有情况下都适用。
通常,如果无法使用 SizeMode.Responsive
(即一小部分自适应布局不可行),则应使用此模式。
访问资源
使用 LocalContext.current
访问任何 Android 资源,如以下示例所示:
LocalContext.current.getString(R.string.glance_title)
我们建议您直接提供资源 ID,以缩减最终 RemoteViews
对象的大小,并启用动态资源,例如动态配色。
可组合项和方法接受使用“提供程序”(如 ImageProvider
)或使用重载方法(如 GlanceModifier.background(R.color.blue)
)的资源。例如:
Column( modifier = GlanceModifier.background(R.color.default_widget_background) ) { /**...*/ } Image( provider = ImageProvider(R.drawable.ic_logo), contentDescription = "My image", )
添加复合按钮
Android 12 中引入了复合按钮。Glance 支持以下类型的复合按钮的向后兼容性:
这些复合按钮会分别显示一个表示“已选中”状态的可点击视图。
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" )
当状态发生变化时,会触发提供的 lambda。您可以存储检查状态,如以下示例所示:
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) } ) } }
您还可以为 CheckBox
、Switch
和 RadioButton
提供 colors
属性以自定义其颜色:
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) ), )