Glance

Glance

  代码示例

API 参考文档
androidx.glance

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

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2025 年 5 月 7 日	1.1.1	-	-	1.2.0-alpha01

声明依赖项

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

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

Groovy

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

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

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-alpha01")
    
    // For AppWidgets support
    implementation("androidx.glance:glance-appwidget:1.2.0-alpha01")

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

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.1.0-beta03"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

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

反馈

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

创建新问题

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

版本 1.2

版本 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，用于为瞥一眼 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 的访问权限，因为当将 R8 与 AGP 7.3 或更高版本（例如 R8 版本 3.3）搭配使用时，系统会通过 API 建模自动执行此操作；当使用 AGP 8.1 或更高版本（例如 D8 版本 8.1）时，系统会针对所有 build 执行此操作。建议不使用 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 的预览注解添加了宽度和高度参数。将 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 代码，而无需膨胀视图。
• 更高级别的组件可用于构建更简单的布局。
• 新的修饰符和主题选项。
• 用于从组合中获取 RemoteView 流的新 API，runComposition

API 变更

• 向 Glance 主题添加了新的 widgetBackground 颜色角色。(Ia2ab8)
• 添加了 GlanceAppWidget.runComposition（I6344c、b/298066147）
• 添加了新的 TopBar 组件 (Ibd361)
• 向 clickable 修饰符添加了替换项。(Iacecf)
• 添加了用于为按钮着色的新 API。在 1.0 版发布之前，此功能应处于实验阶段。(I92523)
• 添加了 runGlanceAppWidgetUnitTest，用于提供对 GlanceAppWidgetUnitTest 调用方法的范围，例如 provideComposable 用于提供用于测试的小型隔离可组合项，onNode 用于在提供的内容中查找 Glance 可组合项元素。这样，您就可以为 appWidget 中的各个可组合函数编写单元测试，以验证在给定特定输入的情况下，该函数是否输出预期的一组一瞥可组合元素。(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-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 中包含这些提交内容。

在向 1.0.0 稳定版过渡的过程中，将 Glance 移到了 rc01。

新功能

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

API 变更

• 为接受 lambda 的所有元素添加了可选键参数。（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 会话的更新机制。现在，AppWidgets 的 Glance 用户应替换 GlanceAppWidget.provideGlance，而不是旧的 Content 方法。由于此操作现在在 worker 中进行，因此现在是加载资源、数据库或网络项的好地方，而无需单独的 worker。

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)
• 使用修饰符使 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”进行了优化的新可组合项。

注意：Glance 使用自己的一组可组合项。不要将 androidx.compose 和 androidx.glance 可组合项组合在一起。

功能

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