您的 2D 移动版或大屏幕 Android 应用默认在 Android XR 中运行,并显示为 3D 空间内的 2D 面板。您可以添加沉浸式 XR 功能来增强现有的 2D Android 应用,将其从平面屏幕体验转变为动态 3D 环境。
将 Android 应用引入 XR 时,请考虑以下重要原则。
- 空间功能:Android XR 为您的应用提供了丰富多样的空间功能,但您不必实现每项功能。有策略地实现这些元素,使其与应用的视觉层次结构、布局和用户体验历程相得益彰。不妨考虑添加自定义环境和多个面板,以打造真正沉浸式的体验。请参阅空间界面设计指南,确定空间元素的最佳集成方式。
- 自适应界面:借助 XR,您可以灵活地设计宽敞的界面,使其能够无缝适应无限画布和可自由调整大小的窗口。其中最重要的一点是,使用我们的大屏设备设计指南针对这种广阔的环境优化应用的布局。即使您的应用目前仅适用于移动设备,您仍然可以利用引人入胜的环境来提升用户体验,但针对大屏设备优化的界面是针对 Android XR 优化应用的最佳方式之一。
- 界面框架:我们建议您使用 Jetpack Compose for XR 构建界面。如果您的应用目前依赖于 View,请参阅在 XR 中使用 View,详细了解如何在使用 View 时利用 Compose 互操作性,或评估直接使用 Jetpack SceneCore 库。
- 在 Play 商店中发布:为确保您的增强型 XR 应用可在 Play 商店中被发现,请执行以下操作:
- 考虑移除所有不必要的功能要求,以简化应用。
- 确保您未在 Google Play 管理中心内选择停用 XR 发布功能,以免您的应用从 Play 商店搜索结果中被排除。
<uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>
有关将 2D 界面组件转换为 3D 组件的提示
遵循以下提示可以让您的应用给用户带来针对 XR 设备进行了优化的感觉,从而显著提升用户体验。
- 优先考虑大屏设备兼容性:确保应用的界面遵循大屏设备设计原则,以确保在宽广的 XR 环境中,文本和内容的易读性达到最佳。
- 有策略地使用空间地图项:找出应用用户体验历程中可通过纳入空间地图项来提升体验并充分利用平台独特功能的重要时刻。
- 在放置空间面板时,应考虑用户的舒适度:在使用空间面板设计布局时,请将其放置在距离用户舒适的位置,以免给用户造成压迫感或感觉太近。
- 为空间布局使用自适应界面:利用窗格和渐进式显示等自适应界面概念,将布局有效分解为多个空间窗格,从而优化信息呈现。
- 将 Orbiter 用于持久性元素和模式:将 Orbiter 预留给导航和控件等持久性和情境用户体验元素。限制使用轨道器,以保持清晰并避免杂乱。
- 谨慎使用 elevation:将空间 elevation 应用于保持静态且不会随内容滚动的临时组件。避免将大面积内容提升到较高层级,以免造成视觉不适并保持平衡的视觉层次结构。
- 使用 Material Design 构建:如果您使用的是最新的 Alpha 版 Material Design 组件和自适应布局进行构建,则可以添加“EnableXrComponentOverrides”封装容器,以在应用中选择启用 XR 更改。如需了解详情,请参阅我们的 适用于 XR 的 Material Design 文档。
Jetpack Compose for XR 引入了用于管理 XR 增强功能的新组件,以便您无需自行管理。例如,您可以使用 SpatialPopup
和 SpatialDialog
替换其 2D 对应项。当空间界面不可用时,这些组件会显示为典型的 2D 界面,并在可能时显示应用的空间界面。使用它们就像只需一行代码更改即可替换相应的 2D 界面元素一样简单。
将对话框转换为 SpatialDialog
// Previous approach Dialog( onDismissRequest = onDismissRequest ) { MyDialogContent() } // New XR differentiated approach SpatialDialog( onDismissRequest = onDismissRequest ) { MyDialogContent() }
将弹出式窗口转换为 SpatialPopup
// Previous approach Popup(onDismissRequest = onDismissRequest) { MyPopupContent() } // New XR differentiated approach SpatialPopup(onDismissRequest = onDismissRequest) { MyPopupContent() }
提升 2D 界面元素
如果您希望通过更精细的控制来提升界面,我们提供了 SpatialElevation
,可让您将应用中的任何可组合项提升到 Z 轴上您使用 SpatialElevationLevel
设置的空间面板上方的一级。这有助于吸引用户的注意力、创建更好的层次结构并提高可辨性,如以下示例所示。
// Elevate an otherwise 2D Composable (signified here by ComposableThatShouldElevateInXr). SpatialElevation(spatialElevationLevel = SpatialElevationLevel.Level4) { ComposableThatShouldElevateInXr() }
代码要点
- 请勿对底部动作条和侧边动作条等大区域和平面进行空间化或提升。
- 请勿提升可随内容滚动的界面元素。
将 2D 组件迁移到 Orbiter
轨道器是浮动元素,通常包含用户可以与之互动的控件。轨道器可以锚定到空间面板或其他实体(例如空间布局)。它们可为内容腾出更多空间,让用户能够快速访问功能,而不会遮挡主要内容。


以下示例代码展示了如何将 2D 界面组件迁移到绕行器。
// Previous approach NavigationRail() // New XR differentiated approach Orbiter( position = OrbiterEdge.Start, offset = dimensionResource(R.dimen.start_orbiter_padding), alignment = Alignment.Top ) { NavigationRail() }
有关轨道器的要点
- 轨道器是用于将现有界面元素附加到空间面板的组件
- 请参阅我们的 Android XR 应用设计指南,验证要为轨道器迁移哪些元素,以及要避免哪些模式。
- 我们建议仅适应少数导航组件,例如侧边导航栏、顶部应用栏或底部应用栏。
- 当未启用空间界面时,轨道器不会显示。例如,它们不会显示在主屏幕空间中,也不会显示在手机、平板电脑和可折叠设备等设备上。
将 2D 组件迁移到空间面板
空间面板是 Android XR 应用界面的基本构建块。
面板可用作界面元素、互动式组件和沉浸式内容的容器。在设计时,您可以为用户控件添加轨道器等组件,并在空间上提升界面元素以吸引用户注意特定互动。
代码要点
- 请参阅 Android XR 应用设计指南,验证要迁移到面板的元素以及要避免的模式。
- 遵循空间面板放置的最佳实践:
- 面板应在距离用户眼睛 1.5 米处的中心位置生成。
- 内容应显示在用户视野中心 41° 的范围内。
- 当用户移动时,面板会保持原位。锚定仅适用于透传。
- 请遵循系统建议的 32 dp 边角半径来设置面板。
- 触摸目标应为 56 dp,且不得小于 48 dp。
- 保持对比度以方便阅读,尤其是在您使用任何透明背景时。
- 遵循 Android 设计颜色原则,并使用 Material Design 颜色系统为应用实现深色和浅色主题。
- 将 Spatial Panels API 与现有界面元素搭配使用。
将二维界面迁移到单个空间面板
默认情况下,您的应用会在 Home Space 中以单个面板的形式显示。
了解如何在 Home Space 和 Full Space 之间切换。如需将该内容放大到全屏,您可以使用 SpatialPanel
。
以下示例展示了如何执行此操作。
if (LocalSpatialCapabilities.current.isSpatialUiEnabled) { Subspace { SpatialPanel( SubspaceModifier .resizable(true) .movable(true) ) { AppContent() } } } else { AppContent() }
将 2D 界面迁移到多个空间面板
您可以为应用的界面使用单个空间面板,也可以将 2D 界面迁移到多个空间面板。如果您选择为应用的界面使用多个面板,则可以定位和旋转面板(类似于在 2D 中布局界面)。首先,您需要明确设计愿景,确定要实现的目标,然后使用空间界面布局 API(SpatialBox
、SpatialRow
、SpatialColumn
、SpatialLayoutSpacer
、SpatialAlignment
)和子空间修饰符来定位和旋转面板。在实现多个面板时,您需要避免一些关键模式。
- 避免面板重叠,以免阻止用户查看重要信息。
- 避免向用户显示过多面板。
- 避免将面板放置在不舒服或不易被注意的位置。示例:放置在用户背后的面板很难被注意到。
- 如需详细了解如何开发空间界面,请参阅我们的完整指南。


SpatialRow(curveRadius = 825.dp) { SpatialPanel( SubspaceModifier .width(384.dp) .height(592.dp) ) { StartSupportingPanelContent() } SpatialPanel( SubspaceModifier .height(824.dp) .width(1400.dp) ) { App() } SpatialPanel( SubspaceModifier .width(288.dp) .height(480.dp) ) { EndSupportingPanelContent() } }
检查空间功能
在决定是否显示特定界面元素时,请避免检查特定 XR 设备或模式。如果检查设备或模式(而非 capability),当给定设备上的 capability 随时间推移而发生变化时,可能会导致问题。而是使用 LocalSpatialCapabilities.current.isSpatialUiEnabled
直接检查是否具有必要的空间化功能,如以下示例所示。这种方法可确保您的应用能够正确适应各种 XR 体验,而无需在每次出现新设备或功能发生变化时进行更新。
if (LocalSpatialCapabilities.current.isSpatialUiEnabled) { SupportingInfoPanel() } else { ButtonToPresentInfoModal() } // Similar check for audio val spatialAudioEnabled = LocalSpatialCapabilities.current.isSpatialAudioEnabled
使用环境来更改用户的周围环境
如果您想通过更改用户的周围环境来营造沉浸感,可以使用环境来实现。在代码中添加环境是一项简单的更改,不会对应用的现有界面造成重大影响。如需详细了解如何设置环境,请务必参阅我们的完整指南。
添加 3D 内容
3D 内容(例如 3D 模型和空间视频)有助于打造更具沉浸感的体验,并增强空间感知。只有在支持空间功能时,您的应用才能显示 3D 内容,因此您需要先 [检查是否支持空间功能][develop/xr/jetpack-xr-sdk/check-spatial-capabilities]。