Glance

Glance

  代码示例

API 参考文档
androidx.glance

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

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2024 年 6 月 12 日	1.1.0	-	-	-

声明依赖项

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

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

Groovy

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

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

    // 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.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)
• 移除了对一览 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 中包含这些提交内容。

新功能

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

API 变更

• 向 Glance 主题添加了新的 widgetBackground 颜色角色。(Ia2ab8)
• 添加了 GlanceAppWidget.runComposition（I6344c、b/298066147）
• 添加了新的 TopBar 组件 (Ibd361)
• 向 clickable 修饰符添加了替换项。(Iacecf)
• 添加了用于色调调节的新 API。在 1.0 版本发布之前，此功能会一直处于实验阶段。（I92523）
• 添加了 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 添加了按钮和 iconbutton API (I0fd6f)
• 添加了 isLinearProgressIndicator、isIndeterminateLinearProgressIndicator、isIndeterminateCircularProgressIndicator 过滤条件，以匹配进度指示器。此外，还包含 hasAnyDescendants 过滤条件，用于测试节点的子层次结构中是否有与特定匹配器匹配的后代 (Ifd426)
• 添加了断言和过滤器，以支持对启动服务 / 活动或广播的点击操作进行测试。此外，还包括测试是否检查了输入元素。（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 中包含这些提交内容。

将 Glance 迁移到了 rc01，正在逐步迁移到 1.0.0 的稳定版本。

新功能

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

API 变更

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

bug 修复

• 不适用，API 文件更改只是重新排序方法 (I5fa95)
• Glance 文本组件样式演示 (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。它看起来更贴近 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 互操作。