Back to Details

glance-canonical-layouts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
To implement a widget Canonical Layout that follows the recommended design patterns:
  1. The project MUST use Jetpack Glance.
  2. You MUST locate the requested layout from the list under Canonical Layout Reference Files.
  3. Copy the layout reference files into your project's target app module (e.g., 
    src/main/java/
    and 
    src/main/res/
    ) in one step to implement the exact design and reduce the number of tool calls.
  4. You MUST set override val 
    sizeMode: SizeMode = SizeMode.Exact
    in the widget provider class.
  5. Validate that your project compiles, updating sample package declarations, import paths, and class names to match the target app's package name.
  6. Clean your project's widget code, removing unused classes (for example, unused buttons).
  7. You MUST register the widget receiver in 
    AndroidManifest.xml
    inside 
    <application>
    after 
    <activity>
    , ensuring 
    android:resource="@xml/..."
    matches the filename of the copied Widget Info XML. Otherwise, the widget won't appear in the widget picker:
<br />
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>
<br />
要实现遵循推荐设计模式的 widget Canonical Layout：
  1. 项目 MUST 使用 Jetpack Glance。
  2. 你 MUST 从 Canonical Layout Reference Files 下的列表中定位所请求的布局。
  3. 将布局参考文件一次性复制到项目的目标 app module（例如 
    src/main/java/
    和 
    src/main/res/
    ）中，以实现精确设计并减少 tool call 数量。
  4. 你 MUST 在 widget provider 类中设置 override val 
    sizeMode: SizeMode = SizeMode.Exact
    。
  5. 验证项目能够编译，并更新 sample package declaration、import path 和 class name，以匹配目标 app 的 package name。
  6. 清理项目的 widget code，移除未使用的类（例如未使用的按钮）。
  7. 你 MUST 在 
    AndroidManifest.xml
    的 
    <application>
    中、
    <activity>
    之后注册 widget receiver，并确保 
    android:resource="@xml/..."
    与复制后的 Widget Info XML 文件名相匹配。否则，该 widget 不会出现在 widget picker 中：
<br />
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>
<br />

Dependencies

依赖项

Add Jetpack Glance dependencies to the app module's 
build.gradle.kts
(
dependencies
block):
  • androidx.glance:glance-appwidget:1.2.0
    or higher
  • androidx.glance:glance-material3:1.2.0
    or higher
  • androidx.glance:glance-appwidget-preview:1.2.0
    or higher
  • androidx.glance:glance-preview:1.2.0
    or higher
Use version 
1.3.0-alpha02
or higher with 
compileSdk = 37
and Android Gradle Plugin (AGP) 9.1.0 or higher (for example, 
agp = "9.1.0"
in 
gradle/libs.versions.toml
) when implementing Snap Scrolling.
If copying sample data repositories that load bitmaps with Coil (such as 
FakeImageGridDataRepository.kt
, 
FakeImageTextListDataRepository.kt
, or 
FakeTextWithImageRepository.kt
), also add an image loading library dependency such as 
io.coil-kt:coil
(e.g., 
implementation("io.coil-kt:coil:2.7.0")
) if one doesn't already exist.
向 app module 的 
build.gradle.kts
（
dependencies
block）中添加 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
    或更高版本
实现 Snap Scrolling 时，当使用 
compileSdk = 37
和 Android Gradle Plugin (AGP) 9.1.0 或更高版本时（例如，在 
gradle/libs.versions.toml
中设置 
agp = "9.1.0"
），请使用版本 
1.3.0-alpha02
或更高版本。
如果复制了使用 Coil 加载 bitmap 的 sample data repository（例如 
FakeImageGridDataRepository.kt
、
FakeImageTextListDataRepository.kt
或 
FakeTextWithImageRepository.kt
），且项目中尚未存在图片加载库依赖项，也应添加 
io.coil-kt:coil
等图片加载库依赖项（例如 
implementation("io.coil-kt:coil:2.7.0")
）。

Canonical layout reference files

Canonical Layout 参考文件

Action list layout (
action_list
)

操作列表布局 (
action_list
)

  • Widget Provider : ActionListAppWidget.kt
  • Layout Composable : ActionListLayout.kt
  • Widget Info XML : sample_action_list_widget_info.xml
  • Data Repository : FakeActionListDataRepository.kt
  • Dimensions : dimens.xml
  • Strings : strings.xml
  • Drawables : 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
  • Components : RoundedScrollingLazyVerticalGrid.kt, ListItem.kt, VerticalListItem.kt, RoundedScrollingLazyColumn.kt, EmptyListContent.kt, NoDataContent.kt
  • Utilities : CollectionsKtx.kt, ActionUtils.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Additional References : CanonicalLayoutActivity.kt, ActionDemonstrationActivity.kt
  • Guidance :
    • Handle list item actions with Glance action callbacks and ensure proper state updates.
  • Widget Provider : ActionListAppWidget.kt
  • 布局 Composable : ActionListLayout.kt
  • Widget Info XML : sample_action_list_widget_info.xml
  • Data Repository : FakeActionListDataRepository.kt
  • 尺寸 : dimens.xml
  • 字符串资源 : strings.xml
  • Drawable 资源 : 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 action callback 处理列表项操作，并确保状态正确更新。

Check list layout (
check_list
)

检查列表布局 (
check_list
)

  • Widget Provider : CheckListAppWidget.kt
  • Layout Composable : CheckListLayout.kt
  • Widget Info XML : sample_check_list_widget_info.xml
  • Data Repository : FakeCheckListDataRepository.kt
  • Dimensions : dimens.xml
  • Strings : strings.xml
  • Drawables : 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
  • Components : ListItem.kt, VerticalListItem.kt, RoundedScrollingLazyColumn.kt, EmptyListContent.kt, NoDataContent.kt
  • Utilities : CollectionsKtx.kt, ActionUtils.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Guidance :
    • Implement checkbox state toggling using action parameters or callbacks to update collection items.
    • Use Glance Action callbacks (for example, 
      actionRunCallback
      , 
      ActionCallback(actionParametersOf(...)
      or 
      actionStartActivity(...)
      ) for widget onClick parameters to handle click events like tapping a checkbox.
  • Widget Provider : CheckListAppWidget.kt
  • 布局 Composable : CheckListLayout.kt
  • Widget Info XML : sample_check_list_widget_info.xml
  • Data Repository : FakeCheckListDataRepository.kt
  • 尺寸 : dimens.xml
  • 字符串资源 : strings.xml
  • Drawable 资源 : 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
  • 指导 :
    • 使用 action parameter 或 callback 实现 checkbox 状态切换，以更新 collection item。
    • 对 widget onClick parameter 使用 Glance Action callback（例如 
      actionRunCallback
      、
      ActionCallback(actionParametersOf(...)
      或 
      actionStartActivity(...)
      ），以处理点击 checkbox 等点击事件。

Expressive toolbar layout (
expressive_toolbar
)

富表现力工具栏布局 (
expressive_toolbar
)

  • Widget Provider : ExpressiveToolbarAppWidget.kt
  • Layout Composable : ExpressiveToolbarLayout.kt
  • Widget Info XML : sample_expressive_toolbar_widget_info.xml
  • Dimensions : dimens.xml
  • Strings : 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
  • Components : Buttons.kt, LayoutComponents.kt
  • Utilities : ActionUtils.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Guidance :
    • Avoid 
      ColorProvider
      import errors: import 
      androidx.glance.unit.ColorProvider
      and use 
      androidx.glance.color.ColorProvider(dayColor, nightColor)
      .
    • Use 
      GlanceModifier.background(Color)
      directly for solid background colors rather than 
      ColorProvider
      .
  • Widget Provider : ExpressiveToolbarAppWidget.kt
  • 布局 Composable : ExpressiveToolbarLayout.kt
  • Widget Info XML : sample_expressive_toolbar_widget_info.xml
  • 尺寸 : dimens.xml
  • 字符串资源 : strings.xml
  • Drawable 资源 : 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 layout (
image_grid
)

图片网格布局 (
image_grid
)

  • Widget Provider : ImageGridAppWidget.kt
  • Layout Composable : ImageGridLayout.kt
  • Widget Info XML : sample_image_grid_widget_info.xml
  • Data Repository : FakeImageGridDataRepository.kt
  • Dimensions : dimens.xml
  • Strings : 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
  • Components : RoundedScrollingLazyVerticalGrid.kt, EmptyListContent.kt, NoDataContent.kt, VerticalListItem.kt
  • Utilities : CollectionsKtx.kt, ImageUtils.kt, ImageAspectRatio.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Guidance :
    • Use solid colors (
      GlanceModifier.background
      ) or local drawables for image items unless an image loading library is configured or requested.
  • Widget Provider : ImageGridAppWidget.kt
  • 布局 Composable : ImageGridLayout.kt
  • Widget Info XML : sample_image_grid_widget_info.xml
  • Data Repository : FakeImageGridDataRepository.kt
  • 尺寸 : dimens.xml
  • 字符串资源 : strings.xml
  • Drawable 资源 : 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
      ）或本地 drawable。

Image text list layout (
image_text_list
)

图文列表布局 (
image_text_list
)

  • Widget Provider : ImageTextListAppWidget.kt
  • Layout Composable : ImageTextListLayout.kt
  • Widget Info XML : sample_image_text_list_widget_info.xml
  • Data Repository : FakeImageTextListDataRepository.kt
  • Dimensions : dimens.xml
  • Strings : strings.xml
  • Drawables : 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
  • Components : ListItem.kt, VerticalListItem.kt, RoundedScrollingLazyColumn.kt, EmptyListContent.kt, NoDataContent.kt
  • Utilities : CollectionsKtx.kt, ImageUtils.kt, ImageAspectRatio.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Guidance :
    • Common Use Cases: News feeds, article lists, workout histories, message feeds, and vertical thumbnail lists.
    • Balance list row height and text clipping when combining thumbnail images with primary and secondary text.
  • Widget Provider : ImageTextListAppWidget.kt
  • 布局 Composable : ImageTextListLayout.kt
  • Widget Info XML : sample_image_text_list_widget_info.xml
  • Data Repository : FakeImageTextListDataRepository.kt
  • 尺寸 : dimens.xml
  • 字符串资源 : strings.xml
  • Drawable 资源 : 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 layout (
long_text
)

长文本布局 (
long_text
)

  • Widget Provider : LongTextAppWidget.kt
  • Layout Composable : LongTextLayout.kt
  • Widget Info XML : sample_long_text_widget_info.xml
  • Data Repository : FakeLongTextRespository.kt
  • Dimensions : dimens.xml
  • Strings : strings.xml
  • Drawables : sample_long_text_preview.png, sample_text_icon.xml, sample_refresh_icon.xml
  • Utilities : FontUtils.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Guidance :
    • Import 
      androidx.compose.ui.unit.times
      if multiplying Dp (for example, 
      2 * padding
      ).
    • Follow sizing rules: ensure dimensions from dimens.xml are used for padding and typography scaling.
  • Widget Provider : LongTextAppWidget.kt
  • 布局 Composable : LongTextLayout.kt
  • Widget Info XML : sample_long_text_widget_info.xml
  • Data Repository : FakeLongTextRespository.kt
  • 尺寸 : dimens.xml
  • 字符串资源 : strings.xml
  • Drawable 资源 : 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
      。
    • 遵循尺寸规则：确保 padding 和 typography scaling 使用来自 dimens.xml 的 dimensions。

Search toolbar layout (
search_toolbar
)

搜索工具栏布局 (
search_toolbar
)

  • Widget Provider : SearchToolBarAppWidget.kt
  • Layout Composable : SearchToolBarLayout.kt
  • Widget Info XML : sample_search_toolbar_widget_info.xml
  • Dimensions : dimens.xml
  • Strings : strings.xml
  • Drawables : 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
  • Components : Buttons.kt, LayoutComponents.kt
  • Utilities : ActionUtils.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Guidance :
    • Avoid 
      ColorProvider
      import errors: import 
      androidx.glance.unit.ColorProvider
      and use 
      androidx.glance.color.ColorProvider(dayColor, nightColor)
      .
    • Use 
      GlanceModifier.background(Color)
      directly for solid background colors rather than 
      ColorProvider
      .
  • 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
      。

Full-bleed image layout and snap scrolling (
snap_scrolling
)

全幅图片布局与 Snap Scrolling (
snap_scrolling
)

  • Widget Provider : FullBleedImageAppWidget.kt
  • Layout Composable : FullBleedImageLayout.kt
  • Widget Info XML : sample_full_bleed_image_widget_info.xml
  • Dimensions : dimens.xml
  • Strings : strings.xml
  • Drawables : 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
  • Utilities : FontUtils.kt, ImageAspectRatio.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Guidance :
    • Set 
      verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)
      on 
      LazyColumn
      for Snap Scrolling.
    • Glance 1.3.0-alpha02 (or higher), Compile SDK 37 (Baklava) or higher, and Android Gradle Plugin (AGP) 9.1.0 or higher are required if implementing Snap Scrolling.
    • Set override val sizeMode: SizeMode = SizeMode.Exact in the widget provider class.
  • 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
  • 指导 :
    • 若要实现 Snap Scrolling，请在 
      LazyColumn
      上设置 
      verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)
      。
    • 实现 Snap Scrolling 时必须使用 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 layout (
standard_toolbar
)

标准工具栏布局 (
standard_toolbar
)

  • Widget Provider : ToolBarAppWidget.kt
  • Layout Composable : ToolBarLayout.kt
  • Widget Info XML : sample_toolbar_widget_info.xml
  • Dimensions : dimens.xml
  • Strings : 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
  • Components : Buttons.kt, LayoutComponents.kt
  • Utilities : ActionUtils.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Additional References : CanonicalLayoutActivity.kt
  • Guidance :
    • See Troubleshooting to avoid 
      ColorProvider
      import errors: use androidx.glance.color.ColorProvider(dayColor, nightColor).
    • Use GlanceModifier.background(Color) directly for solid background colors rather than 
      ColorProvider
      .
  • Widget Provider : ToolBarAppWidget.kt
  • 布局 Composable : ToolBarLayout.kt
  • Widget Info XML : sample_toolbar_widget_info.xml
  • 尺寸 : dimens.xml
  • 字符串资源 : strings.xml
  • Drawable 资源 : 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 layout (
text_with_image
)

文本配图布局 (
text_with_image
)

  • Widget Provider : TextWithImageAppWidget.kt
  • Layout Composable : TextWithImageLayout.kt
  • Widget Info XML : sample_text_with_image_widget_info.xml
  • Data Repository : FakeTextWithImageRepository.kt
  • Dimensions : dimens.xml
  • Strings : 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
  • Utilities : FontUtils.kt, ImageAspectRatio.kt, PreviewAnnotations.kt
  • Theme : Color.kt, Theme.kt, Type.kt
  • Guidance :
    • Follow responsive layout sizing rules to accommodate text and image side-by-side or stacked based on available widget dimensions.
  • Widget Provider : TextWithImageAppWidget.kt
  • 布局 Composable : TextWithImageLayout.kt
  • Widget Info XML : sample_text_with_image_widget_info.xml
  • Data Repository : FakeTextWithImageRepository.kt
  • 尺寸 : dimens.xml
  • 字符串资源 : strings.xml
  • Drawable 资源 : 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 尺寸调整文本和图片，使其并排或堆叠显示。

Troubleshooting

故障排除

  1. Background Colors : Use 
    GlanceModifier.background(Color)
    directly for solid background colors rather than 
    ColorProvider
    , otherwise the background will be transparent.
  2. When using 
    ColorProvider
    (outside of the background), avoid import errors     :
    1. Import type: 
      import androidx.glance.unit.ColorProvider
    2. Use fully qualified creator: 
      androidx.glance.color.ColorProvider(dayColor, nightColor)
  1. 背景颜色：对于纯色背景，直接使用 
    GlanceModifier.background(Color)
    ，而不是 
    ColorProvider
    ，否则背景将保持透明。
  2. 使用 
    ColorProvider
    时（背景之外），避免导入错误    ：
    1. 导入类型：
      import androidx.glance.unit.ColorProvider
    2. 使用完全限定的创建函数：
      androidx.glance.color.ColorProvider(dayColor, nightColor)

Checklist

检查清单

  • [ ] Did you register the widget in the AndroidManifest?
  • [ ] Did you copy the corresponding Widget Info XML file and leave the given values including 
    minWidth
    , 
    minHeight
    , and 
    minResizeHeight
    unchanged?
  • [ ] Did you use the given Glance Theme color values from the corresponding Layout Composable file?
  • [ ] Did you use dimension resource references for 
    android:minWidth
    and 
    android:minHeight
    in appwidget-provider XML definitions?
  • [ ] Did you override 
    val sizeMode: SizeMode = SizeMode.Exact
    in the widget provider class?
  • [ ] 是否已在 AndroidManifest 中注册 widget？
  • [ ] 是否复制了对应的 Widget Info XML 文件，并保持给定值（包括 
    minWidth
    、
    minHeight
    和 
    minResizeHeight
    ）不变？
  • [ ] 是否使用了对应 Layout Composable 文件中给定的 Glance Theme 颜色值？
  • [ ] 是否在 appwidget-provider XML 定义中为 
    android:minWidth
    和 
    android:minHeight
    使用了 dimension resource reference？
  • [ ] 是否在 widget provider 类中覆盖了 
    val sizeMode: SizeMode = SizeMode.Exact
    ？