使用 XR 将您的 Android 应用呈现为 3D 内容

​​

默认情况下，您的 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 商店搜索结果中被排除。

预览版 ：由于存在一个已知问题，Jetpack XR 库的最低 SDK 版本目前高于预期。如果您想将依赖项添加到应用的代码库中，但不想将 minSDK 提高到这么高，则可以使用以下清单条目来解决此问题。

<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

轨道器是浮动元素，包含用于控制空间面板中内容的控件。它们可为内容提供更多空间，让用户能够快速访问功能，而不会遮挡主要内容。

非空间化导航栏

空间化（适用于 XR）导航栏

以下示例代码展示了如何将 2D 界面组件迁移到绕行器。

// Previous approach
NavigationRail()

// New XR differentiated approach
Orbiter(
    position = OrbiterEdge.Start,
    offset = dimensionResource(R.dimen.start_orbiter_padding),
    alignment = Alignment.Start
) {
    NavigationRail()
}

有关轨道器的要点

• 轨道器是用于将现有界面元素附加到空间面板的组件
• 请参阅我们的 Android XR 应用设计指南，验证要为轨道器迁移哪些元素，以及要避免哪些模式。
• 我们建议您仅适应少数导航组件，例如侧边导航栏、顶部应用栏或底部应用栏。
• 当未启用空间界面时，轨道器不会显示。例如，它们不会显示在主屏幕空间中，也不会显示在手机、平板电脑和可折叠设备等设备上。

将 2D 组件迁移到空间面板

空间面板是 Android XR 应用界面的基本构建块。

面板可用作界面元素、互动式组件和沉浸式内容的容器。在设计时，您可以为用户控件添加轨道器等组件，并在空间上提升界面元素以吸引用户注意特定互动。

代码要点

• 请参阅 Android XR 应用设计指南，验证要迁移到面板的元素以及要避免的模式。
• 遵循空间面板放置的最佳实践：
  • 面板应从用户眼睛的中心位置向外延伸 1.5 米。
  • 内容应显示在用户视野中心 41° 的范围内。
• 当用户移动时，面板会保持原位。锚定仅适用于透传。
• 请遵循系统建议的 32 dp 边角半径来设置面板。
• 触摸目标应为 56 dp，且不小于 48 dp。
• 保持对比度以方便阅读，尤其是在您使用任何透明背景时。
• 遵循 Android 设计颜色原则，并使用 Material Design 颜色系统为应用实现深色和浅色主题。
• 将 Spatial Panels API 与现有界面元素搭配使用。

将 2D 界面迁移到单个空间面板

默认情况下，您的应用会在 Home Space 中以单个面板的形式显示。 了解如何在主屏幕和全屏模式之间切换。如需将该内容放大到全屏，您可以使用 SpatialPanel。

以下示例展示了如何执行此操作。

if (LocalSpatialCapabilities.current.isSpatialUiEnabled) {    
    Subspace {
        SpatialPanel(
            SubspaceModifier
                .resizable(true)
                .movable(true)
         ) {
            AppContent(appContainer, widthSizeClass)
        }
    }
} else {
    AppContent(appContainer, widthSizeClass)
}

将 2D 界面迁移到多个空间面板

您可以为应用的界面使用单个空间面板，也可以将 2D 界面迁移到多个空间面板。如果您选择为应用的界面使用多个面板，则可以定位和旋转面板（类似于在 2D 中布局界面）。首先，您需要明确设计愿景，确定要实现的目标，然后使用 Spatial 界面布局 API（SpatialBox、SpatialRow、SpatialColumn、SpatialLayoutSpacer、SpatialAlignment）和子空间修饰符来定位和旋转面板。在实现多个面板时，您需要避免一些关键模式。

• 避免面板重叠，以免阻止用户查看重要信息。
• 避免向用户显示过多面板。
• 避免将面板放置在不舒服或不易被注意的位置。示例：放置在用户背后的面板很难被注意到。
• 如需详细了解如何开发空间界面，请参阅我们的完整指南。

非空间化内容

轨道器中的空间化（适用于 XR 的）媒体控件，以及拆分为多个空间面板的内容

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 内容后，您的应用才能显示 3D 模型，因此您需要确保即使没有您添加的 3D 对象，应用仍能提供出色的体验。

使用 SceneViewer 添加 3D 模型

当您想要向用户展示 3D 模型时，可以通过多种方式解决此问题。当您在服务器上准备好使用 glTF 后，最简单的方法是使用 SceneViewer XR。为此，您可以创建一个显式 intent，该 intent 将在设备上启动 SceneViewer XR 应用。这样，用户就可以查看该对象，并在其周围环境中自由移动和调整其大小。

使用实体“Volume”直接添加 3D 模型

如果您想更好地控制 3D 模型的位置、相对大小或精细动画等，可以直接在应用中加载 glTF 资源。加载 3D 模型后，您可以使用 Volume 可组合项封装 glTF 模型实体，并应用子空间修饰符来控制其呈现方式。借助体积，您可以以声明方式相对于空间界面放置 3D 模型。如需详细了解如何在应用中显示 3D 模型，请参阅创建、控制和管理实体。

注意 ：调用 GltfEntity 会分配系统资源。为确保将这些资源归还给系统，请务必使用 gltfEntity?.dispose() 释放这些系统资源。