display-ai-glasses-with-jetpack-compose-glimmer

术语表

术语	定义
AI 眼镜	可全天佩戴、免提使用的设备，可用于获取信息。其中一些配有显示屏，另一些则仅支持音频。设备配有扬声器、摄像头和麦克风。
显示型 AI 眼镜	在 AI 眼镜的基础上增加了小型私密显示屏，可一目了然地查看与音频输出相协调的视觉内容。
Jetpack Compose Glimmer	用于构建增强型 Android XR 体验的 Compose UI 工具包，针对显示型 AI 眼镜进行了优化。它为透明显示屏提供组件、主题和行为。
投影 Activity	在主机设备（手机）上运行的 Android Activity，其 UI 和交互会投影到已连接的 AI 眼镜设备上。
投影设备	连接到 Android 设备（主机）的 XR 设备。主机会将应用内容投影到投影设备上，供用户交互。
GlimmerTheme	用于提供样式令牌的根级提供者，包括 GlimmerColors、GlimmerTypography 和 GlimmerShapes。
加色显示屏	一种显示技术，其中黑色（#000000）会以 100% 透明的方式呈现。UI 通过向环境中添加光线构建。显示型 AI 眼镜采用加色显示屏。
增强型体验	可增强用户在现实世界中的专注度和临场感的 Android XR 体验。这类体验轻量且具有叠加性，可在用户外出时提供帮助
视角	用于衡量 XR 中感知尺寸的单位。最小可读文字尺寸为 0.6 度（在 1 m 处约为 18sp）。

先决条件

• 移动项目的 minSDK 应设为 37 或更高。如果目标 SDK 低于 37，请将 SDK 提升至 37。AI 眼镜的目标 API 应为 36 或更高。

核心约束

• 不要： 使用 MaterialTheme 或 Material Components。
• 请： 使用 GlimmerTheme 和 Jetpack Compose Glimmer 组件。

限制

• 未详细说明特定硬件设备型号或其独有功能。
• 高度： 不支持标准 Material 3 阴影或高度修饰符。必须使用 Jetpack Compose Glimmer 中的 ShadowScope 或 Depth 令牌。
• 最小尺寸： 可读文字的绝对最小尺寸为 18sp（0.6°）。任何更小的内容都无法通过易读性检查。
• 文字字重： 避免使用“Thin”或“Hairline”字重；它们会导致加色 AR 镜片上出现闪烁和混叠。

1. 设置依赖项

• 设置投影活动： 首先，你需要为 AI 眼镜应用创建一个新的投影活动。如果项目中还没有投影活动，请参阅为 AI 眼镜创建你的第一个活动。使用 references/projectedcontext-source.md 在投影设备上启动眼镜投影活动。
• 移动应用集成： 如果项目包含现有的移动应用，你必须创建一个专用于渲染 Glimmer UI 的新眼镜活动。有关详细配置，请重点参考为 AI 眼镜创建你的第一个活动 。如果尚无启动眼镜活动的方法，请在现有移动应用 UI 中添加一个标记为“在眼镜上启动”的按钮，使用 ProjectedContext 在眼镜上启动眼镜活动。请始终将此按钮放在醒目的位置，例如悬浮操作按钮（FAB）或顶部导航栏中，确保用户能发现投影功能。如果眼镜未连接，请禁用该按钮。不要在手机上启动眼镜活动，只能在 AI 眼镜上启动。如果适合在没有显式启动按钮的情况下自动启动眼镜活动，则可以这样做。
• UI 库： 检查项目是否包含 androidx.xr.glimmer:glimmer 库；如果没有，则必须将其添加到项目中。请参阅声明 Jetpack Compose Glimmer 依赖项，获取最新的依赖项版本。
• 主题设置： 所有 Glimmer 组件都必须包裹在 GlimmerTheme 组合项中，以确保正确解析令牌。
• 强制使用黑色背景： AI 眼镜采用加色显示屏。背景中的任何非黑色都会遮挡现实世界。你必须始终在投影活动的根容器上设置纯黑色背景（Modifier.background(Color.Black)）。
• 字体： 默认字体为 Google Sans Flex。使用 androidx.xr.glimmer.googlefonts 库，并采用默认的类型样式，除非另有说明。使用 createGoogleSansFlexTypography 创建采用 Google Sans Flex 配置的 Typography 实例。像往常一样通过 GlimmerTheme 提供此 Typography 实例。请参阅 references/glimmersansflextypography-source.md 了解配置方法。
• 硬件功能： 不同类型的 AI 眼镜具有不同的功能。要在运行时检查这些功能，请参阅在运行时检查 AI 眼镜的设备功能。
• 硬件权限： 如需请求麦克风和摄像头等硬件权限，请参阅为 AI 眼镜请求硬件权限。
• 硬件访问： 如需使用眼镜摄像头、传感器或访问手机硬件，请参阅使用投影上下文访问 AI 眼镜硬件。

2. 精简并翻译 UI

• 对于 Display AI Glasses，使用 Jetpack Compose Glimmer 框架中的组件构建 UI。
• 使用深度来传达元素的优先级和层次结构。
• 从底部向上设计，尽量减少对现实世界的遮挡。始终将 UI 底部对齐到眼镜显示屏。
• 一次只显示一项内容： 优先保证用户对现实世界的感知。每次只显示一项主要信息（例如，使用 Stack），尽量减少对用户视野的遮挡。避免同时显示多张卡片。
• 颜色对比度： 使用 HCT 色彩空间，确保前景与背景之间的色调差异至少为 70%。关于计算指标，请参阅 references/material-hct-source.md。

3. 映射输入控件

• 将应用交互（例如轻触和滑动）映射到眼镜上可用的硬件控件，例如触摸板。
• 输入方式更偏向一维；用户通常一次只进行一项控件输入。
• 避免嵌套滚动控件。
• Jetpack Compose Glimmer 组件旨在配合标准输入方式使用，例如在 AI 眼镜触摸板上轻触或滑动。
• 使用 System Back 关闭临时状态或详细视图。
• 如需为眼镜 UI 添加输入、焦点和轻触滑动功能，请参阅 Focus in Jetpack Compose Glimmer。
  • 如需详细了解硬件输入，请参阅 Hardware Controls for Display AI Glasses

4. 使用 Jetpack Compose Glimmer 构建

Jetpack Compose Glimmer 是用于为 Display AI Glasses 构建增强体验的 UI 工具包。

主要功能

• Glimmer 主题： 简化的眼镜专用主题，带来最佳可视性。
• 预兼容输入： 默认支持轻触和滑动。
• 预构建组件： 提供经过优化的可组合项，例如 Card、ListItem、Button 等。

Glimmer 中的焦点管理

• Jetpack Compose Glimmer 使用一维焦点搜索。
• 对于可滚动容器，焦点移动是连续的；对于按钮行等元素，焦点移动是离散的。
• 如需让系统自动设置初始焦点，必须在 activity 的 onCreate 方法中将 isInitialFocusOnFocusableAvailable 标志设为 true。有关实现方式的更多信息，请参阅 Focus in Jetpack Compose Glimmer。

实现 Glimmer 样式

可通过 GlimmerTheme 对象访问 Glimmer 样式。请参阅 references/glimmertheme-source.md。

类别	令牌	值 / 作用
颜色	primary	#9BBFFF（焦点色）
颜色	secondary	#4C88E9（焦点色）
颜色	surface	#262626（透明基底 — 渲染为透明）
颜色	outline	#606460（3.dp 边框颜色）
形状	Standard	RoundedCornerShape(36.dp)
形状	Small	RoundedCornerShape(12.dp)

字体排版比例（Google Sans Flex）

严格默认要求： 创建 Glimmer UI 时，必须使用 Google Sans Flex， 除非明确指定了自定义品牌字体。 可变字体设置： 由于 Google Sans Flex 是可变字体，必须配置以下轴：

• 圆润度（ROND）： 始终设为 100f，以呈现标志性的圆润外观。
• 宽度（wdth）： 设为 100f。
• 光学尺寸（opsz）： 设为 9f。
• 字重（wght）： 根据不同角色使用指定值（标题：725f，正文：520f，说明文字：650f）。

样式名称	字号 / 行高	字重轴	宽度	圆润度	光学尺寸
大标题	30.sp / 36.sp	725	100	100	9
中标题	24.sp / 32.sp	725	100	100	9
小标题	20.sp / 28.sp	725	100	100	9
大号正文	30.sp / 36.sp	520	100	100	9
中号正文	24.sp / 32.sp	520	100	100	9
小号正文	20.sp / 28.sp	520	100	100	9
说明文字	18.sp / 28.sp	650	100	100	9

深度级别

在 AI 眼镜上使用阴影模拟深度，通过不同的强调级别营造层次感。 Jetpack Compose Glimmer 控件使用 DepthEffect 和 5 个预设的 DepthEffectLevels。请参阅 references/deptheffect-source.md 和 references/deptheffectlevels-source.md。

示例：

级别	用途
level1	卡片和持久背景 UI 的标准静止状态。
level2	按钮和交互式卡片的标准聚焦 / 按下状态。
ExtraSmall	4.dp

实现 Jetpack Compose Glimmer 组件

卡片

卡片是 Glimmer 中基于表面的基础容器，用于将文本、图像、图标和操作等相关内容组合成一个焦点区域。它们在眼镜环境中建立清晰的深度平面（Z 轴），为文本、图像和图标提供稳定的背景。切勿在列表项中嵌入卡片。

核心实现逻辑

• 表面层级： 卡片设计为置于基础表面上或列表中。如果提供了 onClick lambda，卡片在获得焦点时会自动提供视觉反馈。
• 交互性：
  • 如果 整张卡片作为单一触发器（例如媒体项或设置）：那么 提供 onClick lambda 以启用聚焦效果。
  • 否则： 如果卡片包含多个内部交互元素（例如独立的按钮或开关），请将 onClick 设为 null，以避免焦点争用。

技术文档链接

如果要创建 Glimmer 卡片组件，请阅读：

• 开发者指南： Jetpack Compose Glimmer：卡片
• API 源代码： 使用 references/card-source.md。
• 实现示例： 使用 references/card-samples-source.md。（卡片的基本用法和交互用法）

按钮

按钮是 Glimmer 中触发离散操作的主要控件。它们针对 AI 眼镜的焦点模型进行了专门优化：通过触控板或其他方式将焦点移至按钮时，会显示焦点高亮。

核心实现逻辑

• Glimmer 中有两种按钮可供选择：
  • 标准按钮（必须包含文本标签，可选择是否带前置或后置图标）。当 UI 空间更充裕，或按钮的含义在没有文本时不够明确，应使用此类按钮。
  • 图标按钮（仅含图标）。只有在图标含义清晰易懂时才使用图标按钮。
• 图标按钮和标准按钮都有默认和切换变体：
  • 默认（用于“购买”或“导航”等单次操作）
  • 切换（用于具有选中状态的控件，例如静音按钮）

技术文档链接

如果你正在创建 Glimmer Button 组件，请阅读：

• 开发者指南： Jetpack Compose Glimmer: Buttons
• API 源代码： 使用 references/button-source.md。
• 实现示例： 使用 references/button-samples-source.md。

标题标签

标签是一种药丸形的专用标记组件，设计用于放置在 Card 或一组内容上方，以提供标题。使用标题标签显示简明信息，例如简短标题、名称或状态。

指南和用法

• 空间间距： 在内容上方使用独立的 TitleChip 时，必须使用 TitleChipDefaults.AssociatedContentSpacing（8.dp），以保持视觉层次。
• 交互性： 标题标签仅用于提供信息，不能作为导航目标或被激活。
• 布局： 标题标签中的文本始终居中。标题标签不得换成两行，多余的词应截断。标签最多三个词。

技术文档链接

如果你正在创建 Glimmer Title Chip 组件，请阅读：

• 开发者指南： Jetpack Compose Glimmer: Title Chips
• API 源代码： 使用 references/titlechip-source.md。
• 实现示例： 使用 references/titlechip-samples-source.md。（位于成组内容上方的标题标签）

图标

图标是用于简明表示概念、操作或状态的视觉符号。在 Glimmer 中，图标和图标按钮针对 XR 环境进行了优化，可在加色显示屏上清晰可见，并为交互元素提供凝视响应反馈。

指南和用法

• 尺寸： 使用预定义的 IconSizes（例如 Standard、Large），确保图标清晰易辨，并满足 XR 环境的最小触控目标要求。
• 交互性：
  • 如果图标用作触发器：那么必须使用 IconButton，以提供自动视觉反馈和所需的点击目标内边距。
  • 否则： 对于非交互式指示符或状态符号，使用独立的 Icon。
• 对比度： 切勿使用纯黑色（#000000）作为图标色调；始终使用主题颜色或标准 Glimmer 内容颜色，确保图标在深色背景或真实世界背景上清晰可见。
• 图标库： 默认图标库为 Material Symbols，采用 600 字重、Rounded、Unfilled 样式，除非另有说明。

技术文档链接

如果你正在创建 Glimmer Icon 组件，请阅读：

• 开发者指南： Jetpack Compose Glimmer: Icons
• API 源代码（Icon）： 使用 references/icon-source.md。
• API 源代码（IconButton）： 使用 references/iconbutton-source.md。
• API 源代码（IconSizes）： 使用 references/iconsizes-source.md。

列表

列表是用于在眼镜上浏览和查看多个项目的容器。如果你的使用场景一次只需显示列表中的一个项目，请使用 Glimmer Stack。当列表项类型相同时，请将列表与 Title Chip 配合使用。如果列表项类型不同，也请使用 Glimmer Stack。

指南和用法

• ListItem 插槽： 使用 ListItem 可组合项创建行。它提供了预定义插槽。请参阅 references/listitem-source.md。
• 视觉一致性： 创建包含相似项的列表时，所有项都应始终使用一致的背景颜色（通常为 GlimmerTheme.colors.surface）和圆角半径（标准值为 36.dp）。除非要在视觉上对不同类型的内容分组，否则不要更改这些设置。
• 集成式标题芯片： Glimmer 列表支持集成式标题芯片。如果需要在列表中添加分区标题，那么请启用集成式标题芯片，而不是添加独立的 TitleChip，以保持空间布局一致。
• 垂直排列： 为确保眼镜显示屏上的各项之间有足够的视觉间距，VerticalList 必须始终使用 verticalArrangement = Arrangement.spacedBy(20.dp)。
• 除非另有说明，请确保列表项之间使用默认的 20 dp 间距。

技术文档链接

如果要创建 Glimmer 列表组件，请阅读：

• API 源代码（List）： 请参阅 references/list-source.md。
• API 源代码（ListItem）： 请参阅 references/listitem-source.md。
• API 源代码（ListState）： 请参阅 references/liststate-source.md。

堆叠

堆叠是折叠列表，一次只显示一项内容，视觉效果类似卡片。如果需要一次显示多个项，请使用 Glimmer 列表控件。堆叠中不要使用标题芯片。如果项的类型不同，请使用堆叠来展示；如果项的类型相同，请使用列表。

指南和用法

布局提示

• 堆叠支持高度可变的项。
• 将堆叠控件与显示屏底部对齐。
• 堆叠控件必须比堆叠中最高的项高 66 dp，为遮罩留出空间，并尽量减少在项之间导航时的移动。
• 裁剪和分层： 为确保顶部项后方的项能够正确裁剪并隐藏，必须在每个 item 块内的 Card（或相关容器）上应用 .itemDecoration(CardDefaults.shape) 修饰符。
• 深度阴影： 为保持空间分隔和元素优先级，请使用 Glimmer 的 ShadowScope、DepthEffect 或指定的 DepthEffectLevels 来缩放深度平面。

技术文档链接

如果要创建 Glimmer 堆叠组件，请阅读：

• API 源代码（Stack）： 请参阅 references/stack-source.md。
• API 源代码（StackState）： 请参阅 references/stackstate-source.md。
• API 源代码（StackItemScope）： 请参阅 references/stackitemscope-source.md。

文本

在 Jetpack Compose Glimmer 中，Text 组件基于 Compose 文本组件构建，可用于设置各种文本属性。请务必为文本选择 GlimmerTheme 中的样式。如果需要自定义排版，可以修改应用的主题。

Surface

Surface 是 Glimmer 的基础构建块。请参阅 references/surface-source.md。

Surface 表示一个独立的视觉区域或“物理”边界，可用于按钮和卡片等组件。如果要构建自定义组件，请使用它。

5. 与系统界面集成

• 如需详细了解 AI 眼镜上的通知，请参阅了解 AI 眼镜的通知行为，并了解如何通过通知在 AI 显示眼镜上启动眼镜活动。