glance-canonical-layouts

要实现遵循推荐设计模式的规范布局小组件：

1. 项目必须使用 Jetpack Glance。
2. 必须从规范布局参考文件列表中找到所需布局。
3. 将布局参考文件一次性复制到项目的目标应用模块（例如，src/main/java/ 和 src/main/res/），以实现精确设计并减少工具调用次数。
4. 必须在小组件提供程序类中设置 override val sizeMode: SizeMode = SizeMode.Exact。
5. 验证项目能否编译，并更新示例中的包声明、导入路径和类名，使其与目标应用的包名一致。
6. 清理项目中的小组件代码，移除未使用的类（例如，未使用的按钮）。
7. 必须在 AndroidManifest.xml 的 <application> 中、<activity> 之后注册小组件接收器，并确保 android:resource="@xml/..." 与复制的 Widget Info XML 文件名一致。否则，小组件不会显示在小组件选择器中：

<receiver android:name=".glance.MyReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data
        android:name="android.appwidget.provider"
        android:resource="@xml/my_app_widget_info" />
</receiver>

依赖项

在应用模块的 build.gradle.kts（dependencies 代码块）中添加 Jetpack Glance 依赖项：

• androidx.glance:glance-appwidget:1.2.0 或更高版本
• androidx.glance:glance-material3:1.2.0 或更高版本
• androidx.glance:glance-appwidget-preview:1.2.0 或更高版本
• androidx.glance:glance-preview:1.2.0 或更高版本

实现快照滚动时，请搭配 compileSdk = 37 和 Android Gradle Plugin（AGP）9.1.0 或更高版本使用 1.3.0-alpha02 或更高版本（例如，在 gradle/libs.versions.toml 中设置 agp = "9.1.0"）。

如果复制了使用 Coil 加载位图的示例数据仓库（例如，FakeImageGridDataRepository.kt、FakeImageTextListDataRepository.kt 或 FakeTextWithImageRepository.kt），并且项目中尚未包含图片加载库依赖项，请同时添加一个此类依赖项，例如 io.coil-kt:coil（例如，implementation("io.coil-kt:coil:2.7.0")）。

规范布局参考文件

操作列表布局（action_list）

• Widget Provider： ActionListAppWidget.kt
• 布局 Composable： ActionListLayout.kt
• Widget 信息 XML： sample_action_list_widget_info.xml
• 数据存储库： FakeActionListDataRepository.kt
• 尺寸： dimens.xml
• 字符串： strings.xml
• 可绘制资源： sample_action_list_preview.png、sample_home_icon.xml、sample_power_settings_icon.xml、sample_bulb_icon.xml、sample_thermostat_icon.xml、sample_ac_icon.xml、sample_door_icon.xml、sample_arrow_right_icon.xml、sample_no_data_icon.xml、sample_add_icon.xml
• 组件： RoundedScrollingLazyVerticalGrid.kt、ListItem.kt、VerticalListItem.kt、RoundedScrollingLazyColumn.kt、EmptyListContent.kt、NoDataContent.kt
• 工具： CollectionsKtx.kt、ActionUtils.kt、PreviewAnnotations.kt
• 主题： Color.kt、Theme.kt、Type.kt
• 其他参考： CanonicalLayoutActivity.kt、ActionDemonstrationActivity.kt
• 指南：
  • 使用 Glance 操作回调处理列表项操作，并确保正确更新状态。

清单布局（check_list）

• Widget Provider： CheckListAppWidget.kt
• 布局 Composable： CheckListLayout.kt
• Widget 信息 XML： sample_check_list_widget_info.xml
• 数据存储库： FakeCheckListDataRepository.kt
• 尺寸： dimens.xml
• 字符串： strings.xml
• 可绘制资源： sample_check_list_preview.png、sample_pin_icon.xml、sample_checked_circle_icon.xml、sample_circle_icon.xml、sample_delete_icon.xml、sample_edit_icon.xml、sample_snooze_icon.xml、sample_no_data_icon.xml、sample_add_icon.xml
• 组件： ListItem.kt、VerticalListItem.kt、RoundedScrollingLazyColumn.kt、EmptyListContent.kt、NoDataContent.kt
• 实用工具： CollectionsKtx.kt、ActionUtils.kt、PreviewAnnotations.kt
• 主题： Color.kt、Theme.kt、Type.kt
• 指南：
  • 使用操作参数或回调来更新集合项，实现复选框状态切换。
  • 使用 Glance Action 回调（例如 actionRunCallback、ActionCallback(actionParametersOf(...) 或 actionStartActivity(...)）作为 Widget 的 onClick 参数，以处理点击复选框等点击事件。

富有表现力的工具栏布局（expressive_toolbar）

• Widget Provider： ExpressiveToolbarAppWidget.kt
• 布局 Composable： ExpressiveToolbarLayout.kt
• Widget Info XML： sample_expressive_toolbar_widget_info.xml
• 尺寸： dimens.xml
• 字符串： strings.xml
• Drawables： sample_expressive_toolbar_preview.png、four_side_cookie_background.xml、sample_edit_icon.xml、sample_share_icon.xml、sample_delete_icon.xml、sample_info_icon.xml、sample_add_icon.xml、sample_file_upload_icon.xml、sample_mic_icon.xml、sample_camera_icon.xml
• 组件： Buttons.kt、LayoutComponents.kt
• 实用工具： ActionUtils.kt、PreviewAnnotations.kt
• 主题： Color.kt、Theme.kt、Type.kt
• 指南：
  • 避免 ColorProvider 导入错误：导入 androidx.glance.unit.ColorProvider，并使用 androidx.glance.color.ColorProvider(dayColor, nightColor)。
  • 对于纯色背景，请直接使用 GlanceModifier.background(Color)，而不要使用 ColorProvider。

图片网格布局（image_grid）

• Widget Provider： ImageGridAppWidget.kt
• 布局 Composable： ImageGridLayout.kt
• Widget 信息 XML： sample_image_grid_widget_info.xml
• 数据仓库： FakeImageGridDataRepository.kt
• 尺寸： dimens.xml
• 字符串： strings.xml
• Drawables： sample_image_grid_preview.png, sample_placeholder_image.png, sample_grid_icon.xml, sample_refresh_icon.xml, sample_no_data_icon.xml, sample_add_icon.xml
• 组件： RoundedScrollingLazyVerticalGrid.kt, EmptyListContent.kt, NoDataContent.kt, VerticalListItem.kt
• 实用工具： CollectionsKtx.kt, ImageUtils.kt, ImageAspectRatio.kt, PreviewAnnotations.kt
• 主题： Color.kt, Theme.kt, Type.kt
• 指南：
  • 除非已配置或明确要求使用图像加载库，否则图像项应使用纯色（GlanceModifier.background）或本地 drawables。

图片文本列表布局（image_text_list）

• 小组件提供程序： ImageTextListAppWidget.kt
• 布局 Composable： ImageTextListLayout.kt
• 小组件信息 XML： sample_image_text_list_widget_info.xml
• 数据仓库： FakeImageTextListDataRepository.kt
• 尺寸： dimens.xml
• 字符串： strings.xml
• 可绘制资源： sample_image_text_list_preview.png、sample_placeholder_image.png、sample_image_icon.xml、sample_heart_icon.xml、sample_refresh_icon.xml、sample_no_data_icon.xml、sample_add_icon.xml
• 组件： ListItem.kt、VerticalListItem.kt、RoundedScrollingLazyColumn.kt、EmptyListContent.kt、NoDataContent.kt
• 实用工具： CollectionsKtx.kt、ImageUtils.kt、ImageAspectRatio.kt、PreviewAnnotations.kt
• 主题： Color.kt、Theme.kt、Type.kt
• 指南：
  • 常见用例：新闻动态、文章列表、锻炼记录、消息动态和垂直缩略图列表。
  • 将缩略图与主要文本和次要文本组合使用时，应平衡列表行高度和文本裁切。

长文本布局（long_text）

• 小组件提供程序： LongTextAppWidget.kt
• 布局 Composable： LongTextLayout.kt
• 小组件信息 XML： sample_long_text_widget_info.xml
• 数据仓库： FakeLongTextRespository.kt
• 尺寸： dimens.xml
• 字符串： strings.xml
• 可绘制资源： sample_long_text_preview.png、sample_text_icon.xml、sample_refresh_icon.xml
• 实用工具： FontUtils.kt、PreviewAnnotations.kt
• 主题： Color.kt、Theme.kt、Type.kt
• 指南：
  • 如果要将 Dp 相乘（例如 2 * padding），请导入 androidx.compose.ui.unit.times。
  • 遵循尺寸规则：确保使用 dimens.xml 中的尺寸进行内边距设置和字体排版缩放。

搜索工具栏布局（search_toolbar）

• Widget Provider： SearchToolBarAppWidget.kt
• 布局 Composable： SearchToolBarLayout.kt
• Widget Info XML： sample_search_toolbar_widget_info.xml
• 尺寸： dimens.xml
• 字符串： strings.xml
• Drawable： sample_search_toolbar_preview.png, sample_search_icon.xml, sample_refresh_icon.xml, sample_mic_icon.xml, sample_camera_icon.xml, sample_delete_icon.xml, sample_add_icon.xml, sample_pin_icon.xml
• 组件： Buttons.kt, LayoutComponents.kt
• 工具类： ActionUtils.kt, PreviewAnnotations.kt
• 主题： Color.kt, Theme.kt, Type.kt
• 指南：
  • 避免 ColorProvider 导入错误：导入 androidx.glance.unit.ColorProvider，并使用 androidx.glance.color.ColorProvider(dayColor, nightColor)。
  • 对于纯色背景，请直接使用 GlanceModifier.background(Color)，而非 ColorProvider。

全屏图片布局与吸附滚动（snap_scrolling）

• Widget Provider： FullBleedImageAppWidget.kt
• 布局 Composable： FullBleedImageLayout.kt
• Widget Info XML： sample_full_bleed_image_widget_info.xml
• 尺寸： dimens.xml
• 字符串： strings.xml
• Drawable： sample_full_bleed_image_preview.png, sample_scrim_gradient.xml, sample_placeholder_image.png, sample_app_logo.xml, sample_info_icon.xml, sample_no_data_icon.xml
• 工具类： FontUtils.kt, ImageAspectRatio.kt, PreviewAnnotations.kt
• 主题： Color.kt, Theme.kt, Type.kt
• 指南：
  • 在 LazyColumn 上设置 verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)，以启用吸附滚动。
  • 实现吸附滚动需要 Glance 1.3.0-alpha02（或更高版本）、Compile SDK 37（Baklava）或更高版本，以及 Android Gradle Plugin（AGP）9.1.0 或更高版本。
  • 在 widget provider 类中设置 override val sizeMode: SizeMode = SizeMode.Exact。

标准工具栏布局（standard_toolbar）

• Widget Provider： ToolBarAppWidget.kt
• 布局 Composable： ToolBarLayout.kt
• Widget 信息 XML： sample_toolbar_widget_info.xml
• 尺寸： dimens.xml
• 字符串： strings.xml
• Drawables： sample_toolbar_preview.png、sample_app_logo.xml、sample_search_icon.xml、sample_add_icon.xml、sample_edit_icon.xml、sample_share_icon.xml、sample_mic_icon.xml、sample_camera_icon.xml、sample_videocam_icon.xml
• 组件： Buttons.kt、LayoutComponents.kt
• 工具： ActionUtils.kt、PreviewAnnotations.kt
• 主题： Color.kt、Theme.kt、Type.kt
• 其他参考： CanonicalLayoutActivity.kt
• 指南：
  • 请参阅故障排除，避免 ColorProvider 导入错误：使用 androidx.glance.color.ColorProvider(dayColor, nightColor)。
  • 对于纯色背景，请直接使用 GlanceModifier.background(Color)，而不是 ColorProvider。

图片配文布局（text_with_image）

• Widget Provider： TextWithImageAppWidget.kt
• 布局 Composable： TextWithImageLayout.kt
• Widget 信息 XML： sample_text_with_image_widget_info.xml
• 数据仓库： FakeTextWithImageRepository.kt
• 尺寸： dimens.xml
• 字符串： strings.xml
• Drawables： sample_text_image_preview.png、sample_text_icon.xml、sample_refresh_icon.xml、sample_placeholder_image.png、sample_info_icon.xml、sample_no_data_icon.xml
• 工具： FontUtils.kt、ImageAspectRatio.kt、PreviewAnnotations.kt
• 主题： Color.kt、Theme.kt、Type.kt
• 指南：
  • 遵循自适应布局尺寸规则，根据可用的 Widget 尺寸，让文字和图片并排或堆叠显示。

故障排查

1. 背景颜色：对于纯色背景，请直接使用 GlanceModifier.background(Color)，而不要使用 ColorProvider，否则背景将变为透明。
2. 在（背景之外）使用 ColorProvider 时，避免导入错误：
   1. 导入类型：import androidx.glance.unit.ColorProvider
   2. 使用完全限定的创建方法：androidx.glance.color.ColorProvider(dayColor, nightColor)

检查清单

• [ ] 是否已在 AndroidManifest 中注册此 Widget？
• [ ] 是否已复制对应的 Widget Info XML 文件，并保持给定值不变，包括 minWidth、minHeight 和 minResizeHeight？
• [ ] 是否使用了对应的 Layout Composable 文件中给定的 Glance Theme 颜色值？
• [ ] 是否在 appwidget-provider XML 定义中为 android:minWidth 和 android:minHeight 使用了尺寸资源引用？
• [ ] 是否在 Widget provider 类中重写了 val sizeMode: SizeMode = SizeMode.Exact？