Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

提供灵活的 widget 布局

本页介绍了 Android 12（API 级别 31）中引入的微件尺寸调整优化和更高的灵活性。此外，还详细介绍了如何确定 widget 的大小。

从 Android 12（API 级别 31）开始，您可以通过执行以下操作来提供更精细的大小属性和灵活的布局，如以下部分所述：

指定其他微件尺寸限制。
提供自适应布局或确切布局。

在以前的 Android 版本中，可以使用 OPTION_APPWIDGET_MIN_WIDTH、OPTION_APPWIDGET_MIN_HEIGHT、OPTION_APPWIDGET_MAX_WIDTH 和 OPTION_APPWIDGET_MAX_HEIGHT extra 获取微件的大小范围，然后估算微件的大小，但该逻辑并非在所有情况下都有效。对于以 Android 12 或更高版本为目标平台的小部件，我们建议提供自适应或确切布局。

Android 12 添加了 API，可让您确保微件在具有不同屏幕尺寸的不同设备上更可靠地调整大小。

除了现有的 minWidth、minHeight、minResizeWidth 和 minResizeHeight 属性之外，还可以使用下面这些新的 appwidget-provider 属性：

targetCellWidth 和 targetCellHeight：根据启动器网格单元格定义 widget 的目标大小。定义后，会使用这些属性，而不是 minWidth 或 minHeight。
maxResizeWidth 和 maxResizeHeight：定义启动器允许用户将 widget 尺寸调整到的最大值。

以下 XML 展示了如何使用尺寸属性。

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
  android:targetCellWidth="3"
  android:targetCellHeight="2"
  android:maxResizeWidth="250dp"
  android:maxResizeHeight="110dp">
</appwidget-provider>sizing_attributes.xml

提供自适应布局

如果布局需要根据微件的大小进行更改，我们建议您创建一小组布局，每个布局对一定范围的大小有效。如果无法做到这一点，另一种方法是根据运行时确切微件大小提供布局，如本页所述。

此功能可实现更顺畅的缩放和更好的整体系统运行状况，因为系统不必在每次以不同尺寸显示微件时都唤醒应用。

以下代码示例展示了如何提供布局列表。

override fun onUpdate(
    /* ... */
) {
    val smallView = RemoteViews(
        /* ... */
    )
    val tallView = RemoteViews(
        /* ... */
    )
    val wideView = RemoteViews(
        /* ... */
    )

    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)
}Layouts.kt

假设该 widget 具有以下属性：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minResizeWidth="160dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="200dp">
</appwidget-provider>sizing_constraints.xml

上述代码段的含义如下：

smallView 支持 160dp (minResizeWidth) × 110dp (minResizeHeight) 到 160dp × 199dp（下一个截止点 - 1dp）。
tallView 支持 160dp × 200dp 到 214dp（下一个截止点 - 1）× 200dp。
wideView 支持从 215dp × 110dp (minResizeHeight) 到 250dp (maxResizeWidth) × 200dp (maxResizeHeight)。

注意：微件的大小可能会大于 maxResizeWidth × maxResizeHeight。如需了解详情，请参阅微件大小调整属性。

您的 widget 必须支持 minResizeWidth × minResizeHeight 到 maxResizeWidth × maxResizeHeight 的尺寸范围。在此范围内，您可以决定切换布局的临界点。

提供精确布局

如果一小组自适应布局不可行，您可以改为提供根据微件的显示大小量身定制的不同布局。通常，手机有两种大小（竖屏和横屏模式），可折叠设备有四种大小。

如需实现此解决方案，您的应用需要执行以下步骤：

过载 AppWidgetProvider.onAppWidgetOptionsChanged()，当一组大小发生更改时，就会调用此方法。
调用 AppWidgetManager.getAppWidgetOptions()，这样会返回包含大小的 Bundle。
访问 Bundle 中的 AppWidgetManager.OPTION_APPWIDGET_SIZES 键。

以下代码示例展示了如何提供精确布局。

override fun onAppWidgetOptionsChanged(
    context: Context,
    appWidgetManager: AppWidgetManager,
    id: Int,
    newOptions: Bundle?
) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, id, newOptions)
    // Get the new sizes.
    val sizes = newOptions?.let {
        BundleCompat.getParcelableArrayList(
            it,
            AppWidgetManager.OPTION_APPWIDGET_SIZES,
            SizeF::class.java
        )
    }
    // 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 {
}Layouts.kt

确定微件的大小

每个微件都必须为搭载 Android 12 或更高版本的设备定义 targetCellWidth 和 targetCellHeight，或为所有 Android 版本定义 minWidth 和 minHeight，以指明默认情况下它占用的最小空间。不过，当用户将 widget 添加到主屏幕时，它通常会占用比您指定的最小宽度和高度更多的空间。

Android 主屏幕为用户提供了一个可用空间网格，用户可以在其中放置微件和图标。此网格可能因设备而异；例如，许多手机提供 5x4 网格，而平板电脑可以提供更大的网格。添加微件后，它会拉伸以占据满足其 targetCellWidth 和 targetCellHeight 限制（在搭载 Android 12 或更高版本的设备上）或 minWidth 和 minHeight 限制（在搭载 Android 11 [API 级别 30] 或更低版本的设备上）所需的水平和垂直方向上的最小单元格数。

单元格尺寸和自动外边距因设备而异。根据您希望占用的网格单元数量，使用下表估算微件在典型的 5x4 网格手机上的最小尺寸：

单元格数量（宽 x 高）	竖屏模式下的可用尺寸 (dp)	横屏模式下的可用尺寸 (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)

使用人像模式单元格大小来确定您为 minWidth、minResizeWidth 和 maxResizeWidth 属性提供的值。同样，使用横屏模式单元格大小来确定您为 minHeight、minResizeHeight 和 maxResizeHeight 属性提供的值。

这是因为，单元格宽度在竖屏模式下通常小于在横屏模式下，同样，单元格高度在横屏模式下通常小于在竖屏模式下。

例如，如果您希望在 Google Pixel 4 上将微件宽度调整为一格，则需要将 minResizeWidth 设置为最多 56dp，以确保 minResizeWidth 属性的值小于 57dp，因为在竖屏模式下，一格的宽度至少为 57dp。同样，如果您希望微件高度在同一设备上的一个单元格中可调整大小，则需要将 minResizeHeight 设置为最多 50dp，以确保 minResizeHeight 属性的值小于 51dp，因为在横屏模式下一个单元格的高度至少为 51dp。

每个微件都可以在 minResizeWidth/minResizeHeight 和 maxResizeWidth/maxResizeHeight 属性之间的尺寸范围内调整大小，这意味着它需要适应它们之间的任何尺寸范围。

例如，如需设置 widget 在放置时的默认大小，您可以设置以下属性：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    android:minWidth="180dp"
    android:minHeight="110dp">
</appwidget-provider>default_size_attributes.xml

这意味着，该 widget 的默认尺寸为 3x2 个单元格（由 targetCellWidth 和 targetCellHeight 属性指定），或者为 180x110dp（由 minWidth 和 minHeight 属性指定，适用于搭载 Android 11 或更低版本的设备）。在后一种情况下，以单元格为单位的大小可能会因设备而异。

此外，如需设置微件支持的尺寸范围，您可以设置以下属性：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minResizeWidth="180dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="530dp"
    android:maxResizeHeight="450dp">
</appwidget-provider>supported_size_ranges.xml

根据上述属性，该 widget 的宽度可在 180dp 到 530dp 之间调整，高度可在 110dp 到 450dp 之间调整。只要满足以下条件，该 widget 就可以从 3x2 单元格调整为 5x2 单元格：

设备采用 5x4 网格。
单元格数量与可用尺寸（以 dp 为单位）之间的映射关系遵循本页中显示最小尺寸估算值的表格。
该微件会适应此尺寸范围。

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))Layouts.kt

假设该 widget 使用上述代码段中定义的自适应布局。这意味着，从 180dp (minResizeWidth) x 110dp (minResizeHeight) 到 269x279dp（下一个截止点 - 1），系统会使用指定为 R.layout.widget_weather_forecast_small 的布局。同样，R.layout.widget_weather_forecast_medium 用于 270x110dp 到 270x279dp 的尺寸，R.layout.widget_weather_forecast_large 用于 270x280dp 到 530dp (maxResizeWidth) x 450dp (maxResizeHeight) 的尺寸。

当用户调整微件的大小时，其外观会发生变化，以适应单元格中的各种大小，如以下示例所示。