此页面由 Cloud Translation API 翻译。

Glance

API 参考文档
androidx.glance

使用 Jetpack Compose 样式的 API 构建远程 Surface 的布局。

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2025 年 8 月 27 日	1.1.1	-	1.2.0-beta01	-

声明依赖项

如需添加 Glance 的依赖项，您必须将 Google Maven 代码库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    // For Glance support
    implementation "androidx.glance:glance:1.2.0-beta01"
    // For AppWidgets support
    implementation "androidx.glance:glance-appwidget:1.2.0-beta01"

    // For Wear-Tiles support
    implementation "androidx.glance:glance-wear-tiles:1.0.0-alpha07"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.1.0-beta03"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    // For Glance support
    implementation("androidx.glance:glance:1.2.0-beta01")
    
    // For AppWidgets support
    implementation("androidx.glance:glance-appwidget:1.2.0-beta01")

    // For Wear-Tiles support
    implementation("androidx.glance:glance-wear-tiles:1.0.0-alpha07")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.1.0-beta03"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.2

版本 1.2.0-beta01

2025 年 8 月 27 日

发布了 androidx.glance:glance-*:1.2.0-beta01。版本 1.2.0-beta01 中包含这些提交内容。

bug 修复

将默认 minSdk 从 API 21 移至 API 23（Ibdfca、b/380448311、b/435705964、b/435705223）

版本 1.2.0-alpha01

2025 年 5 月 7 日

发布了 androidx.glance:glance-*:1.2.0-alpha01。版本 1.2.0-alpha01 中包含这些提交内容。

API 变更

currentCompositeKeyHash 现已被弃用。已改用 currentCompositeKeyHashCode。替换 API 使用更多位对相同的哈希进行编码，从而大幅降低了组合层次结构中两个随机无关的组具有相同哈希键的几率。（I4cb6a、b/177562901）
添加了一个新 API，用于为 Glance Image 可组合项和背景图片修饰符指定 Alpha（0f 到 1f）。如果未指定，则保留源图片的 Alpha 值。(I8ad05)
为生成的预览添加了 Glance API。替换 GlanceAppWidget.providePreview 以提供 widget 的预览布局。然后，调用 GlanceAppWidgetManager.setWidgetPreview 来设置预览。(Iced16)
添加了 MultiProcessGlanceAppWidget 以支持多进程配置 (Idbb90)
移除了实验性标记，我们现在支持 lambda（I74d98、b/299361317）
允许为 GlanceAppWidget.runComposition 指定 lambda 接收器 (I84829)
向 requestPinGlanceAppWidget 添加了 previewSize 参数（I9f8f0、b/303256067）

bug 修复

移除了对新平台 API 的访问权限进行手动概述的功能，这是因为在使用 AGP 7.3 或更高版本（例如 R8 版本 3.3）的 R8 时，以及在使用 AGP 8.1 或更高版本（例如 D8 版本 8.1）的所有 build 时，系统会通过 API 建模自动进行 API 访问权限概述。建议未使用 AGP 的客户更新到 D8 版本 8.1 或更高版本。如需了解更多详情，请参阅这篇文章。（If6b4c、b/345472586）
将 glance-appwidget 库更新为 compileSdk 35 (I2e26b)

版本 1.1

版本 1.1.1

2024 年 10 月 16 日

发布了 androidx.glance:glance-*:1.1.1。版本 1.1.1 中包含这些提交内容。

安全修复程序

自此变更起，androidx 会针对 protobuf 4.28.2 进行编译，以解决 CVE-2024-7254。将您对 androidx.glance:glance-appwidget-proto 和 androidx.glance:glance-appwidget-external-protobuf 的依赖项从 1.1.0 版升级到 1.1.1 版，以解决漏洞风险。

版本 1.1.0

2024 年 6 月 12 日

发布了 androidx.glance:glance-*:1.1.0。版本 1.1.0 中包含这些提交内容。

自 1.0.0 以来的重要变更

将 Glance 移至 1.1.0 稳定版。

版本 1.1.0-rc01

2024 年 5 月 14 日

发布了 androidx.glance:glance-*:1.1.0-rc01。版本 1.1.0-rc01 中包含这些提交内容。

新功能

为 Glance 的 Preview 注释添加了宽度和高度参数。将 1.1.0 移至候选版本。

API 变更

向 Scaffold 添加了可选参数。(If753f)
向 Glance @Preview 添加了宽度和高度参数。(Ibabe8)
移除了对 Glance Wear 功能块预览的支持。(I3850a)
添加了用于为 FontStyle 设置自定义权重值的 API。(I7390a)
重命名了 Viewfinder 的 ImplementationMode 枚举，以更好地反映底层实现，并为 TransformationInfo.sourceRotation 添加了固定常量 (Ic6149)

bug 修复

修复了在向后兼容性模式下导致 ViewGroups 出现渲染问题的 bug (I8de92)

外部贡献

实验性 SharedTransitionScope 现在是一个接口，而不是一个类。（Iaf856、b/338415048、b/338414702）

版本 1.1.0-beta02

2024 年 4 月 17 日

发布了 androidx.glance:glance-*:1.1.0-beta02。此版本包含之前版本中缺少的源 JAR。

版本 1.1.0-beta01

2024 年 4 月 3 日

发布了 androidx.glance:glance-*:1.1.0-beta01。版本 1.1.0-beta01 中包含这些提交内容。

版本 1.1.0-alpha01

2024 年 2 月 7 日

发布了 androidx.glance:glance-*:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

新功能

不需要 UI Automator 的 Glance 单元测试库。可以直接测试 Glance 代码，而无需膨胀视图。
更高级别的组件，可实现更简单的布局。
新的修饰符和主题选项。
用于从组合中获取 RemoteViews 流的新 API，runComposition

API 变更

向 Glance 主题添加了新的 widgetBackground 颜色角色。(Ia2ab8)
添加了 GlanceAppWidget.runComposition（I6344c、b/298066147）
添加了新的 TopBar 组件 (Ibd361)
向 clickable 修饰符添加了替换项。(Iacecf)
添加了用于为按钮着色的新 API。在 1.0 正式版发布之前，此功能应处于实验阶段。(I92523)
添加了 runGlanceAppWidgetUnitTest，该 runGlanceAppWidgetUnitTest 提供在 GlanceAppWidgetUnitTest 上调用方法（例如 provideComposable，用于提供一个用于测试的小型隔离可组合项；onNode，用于在提供的内容中查找 Glance 可组合元素）的范围。这样一来，您就可以为 appWidget 中的各个可组合函数编写单元测试，以验证在给定特定输入的情况下，该函数是否会输出预期的一组 Glance 可组合元素。(I2f682)
在语义中添加了 testTag 修饰符，以便在单元测试中使用。(I8f62f)
更新了 TitleBar - 文本和图标可单独着色。(Ia0a60)
添加了 scaffold 组件 (I8a736)
添加了 hasActionRunCallbackClickAction 过滤条件和 assertHasActionRunCallbackClickAction 断言，以测试 actionRunCallack。此外，还为与操作相关的测试过滤条件添加了其他简写变体函数 - hasStartActivityClickAction<activityClass>(..)、hasStartServiceAction<receiverClass>(..)、hasSendBroadcastAction<receiverClass>(..)。为其 assertHasXXX 对应项添加了类似的变体。(Ieca63)
移动未发布的 API。将修饰符从内部更改为公开但受库限制 (If2a08)
添加了 onCompositionError 方法，开发者可以在发生错误时运行代码 (I9b56f)
向 Glance 添加了按钮和图标按钮 API (I0fd6f)
添加了 isLinearProgressIndicator、isIndeterminateLinearProgressIndicator、isIndeterminateCircularProgressIndicator 过滤条件，以匹配进度指示器。添加了 hasAnyDescendants 过滤条件，用于测试节点在其子层次结构中是否具有与特定匹配器 (Ifd426) 匹配的后代
添加了断言和过滤器，以实现对启动服务 / activity 或广播的点击操作的测试。还包括测试输入元素是否已勾选。(I3041c)

版本 1.0.0

版本 1.0.0-alpha07

2025 年 8 月 27 日

发布了 androidx.glance:glance-wear-tiles:1.0.0-alpha07。版本 1.0.0-alpha07 中包含这些提交内容。

新功能

Glance Wear 块现已弃用，并将在即将发布的版本中移除。它将被新的 Glance Wear widget 库取代。

API 变更

废弃了 glance-wear-tiles (I82afd)
移除了过时的 @RequiresApi(21) 注释 (Ic4792)
移除了过时的 @RequiresApi(21) 注解 (I9103b)
移除未使用的模块。我们不会继续使用“模板”。（I3fc90、b/430070874）
使用 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本才能使用 (Idb6b5)
修复了 API 委员会反馈的问题 (I284c8)
添加了用于为按钮着色的新 API。在 1.0 发布之前，此功能应为实验性功能 (I92523)
更新了 API 文件，以便为兼容性抑制添加注解。（I8e87a、b/287516207）
现在，所有 tile-renderer API 都全面支持 protolayout 类型。(I428b0)
合并了 d、e、f、g 路径的公共 API 文件和实验性 API 文件（I03646、b/278769092）
为 Button、Checkbox、RadioButton 和 Switch 添加了 *Defaults API。它使 Glance 更贴近 Jetpack Compose 的模式。(I94828)
新的 Glance 模板模块 (I94459)
我们为 TileRenderer 添加了对 androidx.wear.protolayout 类型的支持 (I4ac7f)
更多已废弃隐藏函数的返回值类型可为 null (Ibf7b0)
添加了 @JvmDefaultWithCompatibility 注解（I8f206、b/251463569）
添加了对使用 lambda 作为回调的支持 (Ia0bbd)

bug 修复

将 glance-appwidget 库更新为 compileSdk 35 (I2e26b)

版本 1.0.0-alpha06

2024 年 2 月 7 日

发布了 androidx.glance:glance-appwidget-preview:1.0.0-alpha06 和 androidx.glance:glance-preview:1.0.0-alpha06。版本 1.0.0-alpha06 中包含这些提交内容。

新功能

更新了版本，以遵循主要的 Glance 模块。

版本 1.0.0

2023 年 9 月 6 日

发布了 androidx.glance:glance-*:1.0.0。版本 1.0.0 中包含这些提交内容。

1.0.0 的主要功能

将 Glance 移至稳定版 1.0.0

版本 1.0.0-rc01

2023 年 7 月 26 日

发布了 androidx.glance:glance-*:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

将 Glance 移至 rc01，为 1.0.0 稳定版做准备。

新功能

向操作 lambda 添加了关键参数，以实现更稳定的操作调用。
添加了向 startActivity 操作提供 ActvityOptions 的功能。
添加了对 Android 14 的支持

API 变更

为接受 lambda 的所有元素添加了可选的 key 参数。（Id96c1、b/282445798）
添加了对为 actionStartActivity 设置 ActivityOptions 软件包的支持 (I6a08d)
合并了 d、e、f、g 路径的公共 API 文件和实验性 API 文件（I03646、b/278769092）
不适用，API 文件更改只是重新排序了方法 (I5fa95)
添加了用于为 GlanceAppWidgetReceiver 请求设置 CoroutineContext 的 API (I0a100)
添加了一个新 API，用于为 LazyColumn 和 LazyVerticalGrid 提供 ActivityOptions，该 ActivityOptions 将用于列表中的所有操作。(Id8d71)

bug 修复

不适用，API 文件更改只是重新排序了方法 (I5fa95)
概览文本组件样式演示（Ie78a4）

版本 1.0.0-beta01

2023 年 5 月 10 日

发布了 androidx.glance:glance-*:1.0.0-beta01。版本 1.0.0-beta01 中包含这些提交内容。

新功能

将库移至 Beta 版。
支持使用 GlanceTheme 进行主题设置，添加了 glance-material 和 glance-material3 模块，以支持 Glance 中的 Material 2 和 Material 3 样式主题。
为文本 API 添加了对 FontFamily 的支持。
将 GlanceAppWidget 移到了基于 WorkManager 会话的更新机制。Glance for AppWidgets 的用户现在应替换 GlanceAppWidget.provideGlance，而不是旧的 Content 方法。由于此操作现在在工作器中进行，因此现在可以在此处加载资源、数据库或网络项，而无需单独的工作器。

API 变更

为 Button、Checkbox、RadioButton 和 Switch 添加了 *Defaults API。它使 Glance 更贴近 Jetpack Compose 的模式。(I94828)
新的 Glance 模板模块 (I94459)
将 ResourceColorProvider 设为模块内部。重大变更。这是必需的，因为 ResourceColorProvider 仅应用于动态主题，以避免出现某些颜色是动态资源而某些颜色是完全解析的资源的情况。(Ib0db7)
添加了 FontFamily 作为 TextStyle 的选项。（Ic19ba、b/274179837）
更改了 Enum.valueOf 的值形参名称 (Ia9b89)
枚举 valueOf 抛出的更多异常 (I818fe)
更新了 GlanceAppWidget 以使用 provideGlance 作为主要入口点。GlanceAppWidget.Content 现已废弃。(I202b5)
添加了一个用于为图片提供着色颜色的选项（I26192、b/212418562）
更多已废弃隐藏函数的返回值类型可为 null。(Ibf7b0)
添加了 @JvmDefaultWithCompatibility 注解 (I8f206)
移除了未使用的 SingleEntityTemplateData.displayHeader。(I7f094)
添加了对使用 lambda 作为回调的支持 (Ia0bbd)
将 DayNightColorProvider 移到了 Glance 模块（I1842c、b/256934779）
从模板中移除 LocalColorProvider。模板现在将使用 GlanceTheme.colors (Ic15e2)
移除了 Text(style: TextStyle) 中的可为 null 性（I7123b、b/237012816）
将默认文本颜色设为黑色。移除了可为 null 性（I3072c、b/237012816）
将动态主题 ColorProviders 设为自己的对象。使 ResourceColorProvider 成为模块的内部变量。（Id0e2d、b/237012816）
将“未定义”类别添加到 ImageSize。(I2fa39)
移除了已弃用的 GlanceAppWidget.Content 函数 (Ib05f6)
将修饰符作为参数添加到 AndroidRemoteViews。(I515d4)
添加了 GlanceAppWidget.compose 以简化单元测试 (Ie9b28)

bug 修复

为 Glance 文本字体添加了演示微件 (I5c3d7)
使用 Modifier 使 AndroidRemoteViews 可调整大小。
修复了主题颜色不一致的问题
所有资源现在都添加了前缀，以避免冲突

版本 1.0.0-alpha05

2022 年 10 月 5 日

发布了 androidx.glance:glance:1.0.0-alpha05、androidx.glance:glance-appwidget:1.0.0-alpha05 和 androidx.glance:glance-wear-tiles:1.0.0-alpha05。版本 1.0.0-alpha05 中包含这些提交内容。

新功能

向 GlanceAppWidgetManager 添加了 requestPinGlanceAppWidget，使应用能够提示用户将基于 Glance 的 widget 添加到其主屏幕。(Ic6e47)
向 GlanceAppWidgetReceiver 添加了 ACTION_DEBUG_UPDATE，使开发者能够在已取得 root 权限的设备和模拟器上强制从 adb 更新其 widget。(I94ae1)

API 变更

移除了 Glance 模板中的标题操作按钮，以简化用例。(Ie4387)
重构了 Single Entity 模板，以重复使用 Block 子系统设计。(Iecd2c)
重构了 Glance List 模板，以使用 Text/Image/Action Block 设计。(If0cc1)
为 TextBlock 和 ImageBlock 添加了优先级数字范围。(I73100)

bug 修复

移除了 Material3 依赖项。(I28d1c)
迁移到更加一致的系统，以便在 Glance 模板布局中添加外边距和间距。(I29773)
修复了会导致系统无法构建缩减版本的格式有误的 Proguard 规则。

版本 1.0.0-alpha04

2022 年 8 月 10 日

发布了 androidx.glance:glance:1.0.0-alpha04、androidx.glance:glance-appwidget:1.0.0-alpha04 和 androidx.glance:glance-wear-tiles:1.0.0-alpha04。版本 1.0.0-alpha04 中包含这些提交内容。

新功能

添加了 Button 着色功能。
添加了 GlanceComposable 注解，可更好地进行编译时检查。
添加了 Wear 专用的 Glance 功能。

API 变更

更新了 Glance Gallery Data API 和精简视图。(Ibc7a8)
添加了用于配置按钮的 ButtonColors。（Iea88d、b/236305351）
将 ColorProvider.resolve 重命名为 ColorProvider.getColor (Ic9dfe)
向 TextStyle 添加了 copy() 方法。(I9aef6)
添加了 ColorProviders 类，可用作 Glance 主题的一部分。（I848b9、b/237012816）
为列表样式和折叠视图添加了列表模板支持。(I50cdc)
为 GlanceModiier 和 GlanceCurvedModifier 添加语义。(Ifda7e)
添加了 GlanceComposable 注解。(I5dbf0)
将 Glance 模板移到主 Glance 项目中。(I9db94)
添加了 ColorProvider.resolve()（Ife532、b/214733442）
添加了从现有的 appWidgetId 中获取 GlanceId 或从配置 activity 中获取 intent 的新方法（Icb70c、b/230391946）
添加 GlanceComposable 注解。(I2c21f)
添加了用于在 GlanceAppWidget 之外运行组合的 GlanceRemoteViews。(I18f92)
移除了 ProgressIndicatorDefaults 中的 Color。(I40299)
根据 API 审核反馈的要求，将 ActionCallback 的 onRun 方法重命名为 onAction，以便与公共 API 保持一致。(Icfa57)
将 Glance 模板布局转换为使用地图 (I46bfd)
添加了 RadioButton 可组合项 (I4ecce)
添加了用于组合 Wear 土块的 GlanceWearTiles (Ia9f65)
向 GlanceCurvedModifier 添加了可点击项 (Iec2a0)
将 CurvedRow 作为作用域实现，并创建 DSL 以添加常规的可组合项和/或曲线元素。还在 proto 卡片中添加了 curvedLine 和 curvedSpacer，它们会转换为 ArcLine 和 ArcSpacer (Ib955b)
更新了 core 和 appcompat 中的可为 null 性，以匹配 Tiramisu DP2 (I0cbb7)
在 glance-wear-tiles 中添加了对 RuncallbackAction 的支持，目前仅支持不带参数的 RunCallbackAction (Ide64a)

外部贡献

由于 test-coroutines-lib 迁移，更新了 :compose:ui:ui-test API (updateApi) (I3366d)

版本 1.0.0-alpha03

2022 年 2 月 23 日

发布了 androidx.glance:glance-*:1.0.0-alpha03。版本 1.0.0-alpha03 中包含这些提交内容。

新功能

简化状态定义，默认采用“偏好设置”。

API 变更

将 PreferencesGlanceStateDefinition 作为默认的状态处理方法，从而简化状态处理。移除了 GlanceAppWidget.updateAppWidgetState，并引入了默认使用 Preferences 的 updateAppWidgetState。(I58963)
添加了 Glance TemplateText 类，并更新了模板设计 (I4e146)
为 Freeform 模板添加了概要基础架构 (If03d6)
更新了 SingleEntityTemplate 布局 (If925d)
添加了 LazyVerticalGrid (I5f442)
在 SingleEntityTemplate 上使用 ColorProvider (I01ee0)
更新了模板类名称 (I3720e)
添加了 LinearProgressIndicator 和 CircularProgressIndicator 可组合项。(Ie116b)

bug 修复

实现了初始 Glance 模板，定义了“单项模板”数据和示例模板布局 (I35837)
默认情况下，对图块内容进行中心对齐 (I264be)
修复了 glance-wear-tiles 中的 fillMaxSize/Width/Height 存在的 bug (I0a39f)

版本 1.0.0-alpha02

2022 年 1 月 26 日

发布了 androidx.glance:glance-*:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

新功能

此版本包含一组 API，这些 API 用于使用具有可组合项（针对“支持 Glance”进行过优化）的 Compose 运行时构建 Wear 卡片

通过扩展 GlanceTileService（用于在可组合 Content() 函数中创建图块的服务）来声明穿戴式设备图块服务。
穿戴式设备图块专用 Glance 可组合项：CurvedRow、CurvedText。
通过定义 TimelineMode.SingleEntry 和 TimelineMode.TimeBoundEntries，处理图块的不同时间轴模式。
LocalTimeInterval，表示特定时间间隔的 Local 组合。
BorderModifer 是在元素周围应用边框的 GlanceModifier。

此版本还向 AppWidget Glance 添加了进度指示器。

API 变更

添加了 LinearProgressIndicator 和 CircularProgressIndicator 可组合项。(Ie116b)
将 actionStartBroadcastReceiver 更改为 actionSendBroadcast (I7d555)
将 Context 传递给 GlanceAppWidget onDelete 回调 (I4c795)

bug 修复

当 OPTIONS_APPWidget_SIZES 存在，但为空时，能够正确处理。(I01f82)

版本 1.0.0-alpha01

2021 年 12 月 15 日

发布了 androidx.glance:glance:1.0.0-alpha01、androidx.glance:glance-appwidget:1.0.0-alpha01 和 androidx.glance:glance-appwidget-proto:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

初始版本的功能

Glance 的第一个版本包含第一组使用 Compose Runtime 构建 AppWidget 的 API，以及一组针对“Glanceables”进行了优化的新可组合项。

功能

使用 GlanceAppWidget 和 GlanceAppWidgetReceiver 声明您的应用 widget。
使用最初的一组 Glance 可组合项编写界面：Box、Row、Column、Text、Button、LazyColumn、Image、Spacer。
使用 GlanceModifier 方法将修饰符应用于可组合项。
处理与预定义的 Action 之间的用户交互。
使用 ActionParameters 向 Action 提供参数。
通过定义 SizeMode.Single、SizeMode.Exact 或 SizeMode.responsive 来处理不同的尺寸模式。
通过提供 GlanceStateDefinition 保留 GlanceAppWidget 状态。
本地组合（如 LocalContext、LocalState、LocalGlanceId、LocalSize）。
使用 AndroidRemoteViews 可组合项与现有的 RemoteViews 互操作。