适用于 Jetpack XR 的 ARCore

借助感知功能将数字内容带入现实世界。
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2026 年 3 月 25 日 - - - 1.0.0-alpha12

声明依赖项

如需添加适用于 Jetpack XR 的 ARCore 的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 制品库 。

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

Groovy

dependencies {
    implementation "androidx.xr.arcore:arcore:1.0.0-alpha12"

    // Optional dependencies for asynchronous conversions
    implementation "androidx.xr.arcore:arcore-guava:1.0.0-alpha12"
    implementation "androidx.xr.arcore:arcore-rxjava3:1.0.0-alpha12"
}

Kotlin

dependencies {
    implementation("androidx.xr.arcore:arcore:1.0.0-alpha12")

    // Optional dependencies for asynchronous conversions
    implementation("androidx.xr.arcore:arcore-guava:1.0.0-alpha12")
    implementation("androidx.xr.arcore:arcore-rxjava3:1.0.0-alpha12")
}

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

反馈

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

创建新问题

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

1.0 版

1.0.0-alpha12

2026 年 3 月 25 日

发布了 androidx.xr.arcore:arcore-*:1.0.0-alpha12。版本 1.0.0-alpha12 中包含 这些提交内容。

API 变更

  • 将 Config.augmentedObjectCategories 从列表更改为集。(I25a64、b/487376359)
  • 类型 androidx.xr.arcore.Eye 和 androidx.xr.arcore.Hand。（I42438、b/449032900）
  • 添加了 Session.create 重载，以允许传递 Android Context 进行资源范围限定。(I7d3fe、b/415805990、b/477386334)
  • 将 FakeRuntimeAnchor.ANCHOR_RESOURCE_LIMIT 更改为 FakeRuntimeAnchor.anchorResourceLimit。（I90841、b/431992235）
  • 将 TiltGesture API 设为实验性，因为该 API 将来可能会发生变化或被移除。如需使用此 API，请选择启用 @ExperimentalGesturesApi (Ic9858)
  • 添加了在配置中为 AugmentedObject 跟踪设置类别的功能 (I1f6e4, b/480220930)

bug 修复

  • 通过使用 PerceptionRuntimeFactory 的实际位置更新 META-INF/services/ 文件，修复了 Chrome 的 build。(I7a801、b/481288291)

1.0.0-alpha11

2026 年 2 月 25 日

发布了 androidx.xr.arcore:arcore-*:1.0.0-alpha11。版本 1.0.0-alpha11 中包含 这些提交内容。

1.0.0-alpha10

2026 年 1 月 28 日

发布了 androidx.xr.arcore:arcore-*:1.0.0-alpha10。版本 1.0.0-alpha10 中包含 这些提交内容。

新功能

  • 引入了 TiltGesture API，提供了一个响应式 Flow，用于稳定检测设备倾斜（向上/向下）状态以及过渡进度。(Ic269f、b/448152779)
  • 适用于 Jetpack XR 的 ARCore 现在使用 XR 运行时日志记录机制。如需了解详情，请参阅 androidx.xr.runtime.Log。(l52735、b/448697662)

API 变更

  • Geospatial.createPoseFromGeospatialPose 现在可在启用 OpenXR 的设备上运行。（l362c6）

1.0.0-alpha09

2025 年 12 月 3 日

发布了 androidx.xr.arcore:arcore-*:1.0.0-alpha09。版本 1.0.0-alpha09 中包含 这些提交内容。

1.0.0-alpha08

2025 年 11 月 19 日

发布了 androidx.xr.arcore:arcore-*:1.0.0-alpha08。版本 1.0.0-alpha08 中包含 这些提交内容。

新功能

  • 适用于 Jetpack XR 的 ARCore 现在支持提供“面向 AR 的 Google Play 服务”的设备。
  • 添加了 VPS 可用性和姿势转换的 Geospatial API (I144dc)

1.0.0-alpha07

2025 年 10 月 22 日

发布了 androidx.xr.arcore:arcore-*:1.0.0-alpha07。版本 1.0.0-alpha07 中包含 这些提交内容。

bug 修复

  • :xr:arcore:arcore-openxr 作为实现依赖项添加到了 :xr:arcore:arcore (I47315, b/446999229)

1.0.0-alpha06

2025 年 9 月 24 日

发布了 androidx.xr.arcore:arcore-*:1.0.0-alpha06。版本 1.0.0-alpha06 中包含 这些提交内容。

API 变更

  • 对 ARCore 的测试支持已迁移到 xr:arcore:arcore-testing 模块。(I25469)
  • 添加了 ArDevice 和 RenderViewpoint，以允许应用检索设备的姿势和显示配置以进行渲染。(Ib7e3f)
  • 使用 HAND_JOINT_TYPE_ 前缀重命名了 HandJointType 枚举。(I3f7cd)
  • HandJointType 已从 xr:runtime:runtime 移至 xr:arcore:arcore。（Iadb9c、b/409058039）
  • Hand.State 现在以一种格式公开了 java.nio.FloatBuffer，其中包含关节姿势，以便性能导向型应用轻松访问。(I55e27)

1.0.0-alpha05

2025 年 7 月 30 日

发布了 androidx.xr.arcore:arcore:1.0.0-alpha05、androidx.xr.arcore:arcore-guava:1.0.0-alpha05 和 androidx.xr.arcore:arcore-rxjava3:1.0.0-alpha05。版本 1.0.0-alpha05 中包含 这些提交内容。

新功能

  • 添加了 getPrimaryHandSide，以便开发者可以获取手部信息 (I270bd)
  • 添加了 Geospatial 检查 VPS 可用性 API (I58573)
  • 为 checkVpsAvailability 添加了 ARCore API (Idbded)
  • 为 :xr:arcore:arcore-rxjava3 添加了 stateFlowable 扩展函数，供 Java 开发者使用。（I083aa、b/427247794）

API 变更

  • Config *Mode 值已重命名，以反映其行为。(I6d247、b/414648065)
  • 主要的 ARCore 工件 (xr:arcore:arcore) 将仅包含 Kotlin 样式的异步 API。Java 开发者可以依赖 xr:arcore:arcore-rxjava3 库来访问兼容的 API。（Ia525e、b/422794329）
  • 主要的 ARCore 工件 (xr:scenecore:scenecore) 将仅包含 Kotlin 样式的异步 API。Java 开发者可以依赖 xr:arcore:arcore-guava 库来访问兼容的 API。(Iffcb4、b/422773524)
  • 为 AnchorGuava 添加了 Anchor.persistAsync()，供 Java 开发者使用。（I4af1c、b/425984631）
  • 为 EarthGuava 添加了 Earth.createAnchorOnSurfaceAsync(Session, Double, Double, Double, Quaternion, Surface)，供 Java 开发者使用。(I66357、b/425992992)
  • Java 开发者将使用 GltfModel.kt 中的 GltfModel.createAsync 的扩展函数。GltfModel 中的异步函数将被删除。(I0af60)
  • 此库现在使用 JSpecify nullness 注解，这些注解属于 type-use 类型。Kotlin 开发者应使用以下编译器实参来强制执行正确用法：-Xjspecify-annotations=strict（这是 Kotlin 编译器从 2.1.0 版开始的默认实参）（Ia8420、b/326456246）
  • 为 :xr:arcore:arcore-rxjava3 添加了 subscribeAsFlowable 扩展函数，供 Java 开发者使用。（Id3e49、b/427277298）

1.0.0-alpha04

2025 年 5 月 7 日

发布了 androidx.xr.arcore:arcore:1.0.0-alpha04。版本 1.0.0-alpha04 中包含 这些提交内容。

API 变更

  • 使用 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本。(Idb6b5)
  • TrackingState 和 HandJointType 已从 ARCore 移至 Runtime。
  • Hand.State.isActive (boolean) 已更改为 Hand.State.trackingState (androidx.xr.runtime.TrackingState)。
  • 如果 UUID 无效，Anchor.load 会返回 Anchor.AnchorLoadInvalidUuid。

1.0.0-alpha03

2025 年 2 月 26 日

发布了 androidx.xr.arcore:arcore:1.0.0-alpha03，该版本与上个 Alpha 版相比没有明显变化。版本 1.0.0-alpha03 中包含 这些提交内容。

1.0.0-alpha02

2025 年 2 月 12 日

发布了 androidx.xr.arcore:arcore:1.0.0-alpha02。版本 1.0.0-alpha02 中包含 这些提交内容。

新功能

  • 添加了手部跟踪支持。使用 Hand.left 和 Hand.right 访问跟踪信息。
  • 生成锚点的 API（Anchor.create、Anchor.load、Plane.createAnchor）现在都会返回 AnchorCreateResult 并正确实现 AnchorCreateResourcesExhausted。

bug 修复

  • Anchor.detach 不再因与会话更新线程发生竞态条件而导致严重崩溃。
  • Anchor.create 在模拟器上运行时更加稳定

1.0.0-alpha01

2024 年 12 月 12 日

发布了 androidx.xr.arcore:arcore-* 1.0.0-alpha01。

初始版本的功能

适用于 Jetpack XR 的 ARCore 库受现有 ARCore 库的启发，提供了将数字内容与现实世界融合的功能。此库包括动作跟踪、持久锚点、命中测试和平面识别（带有语义标签，例如地面、墙壁和桌面）。如需详细了解如何使用适用于 Jetpack XR 的 ARCore，请参阅开发者指南 。

  • Session：适用于 Jetpack XR 的 ARCore 在后台使用 Jetpack XR 运行时来提供功能。您将使用会话与大多数适用于 Jetpack XR 的 ARCore API 进行交互，因此请查看其文档。

  • Plane：使用平面了解周围的世界。每个平面都有一个 Label，用于对其进行语义描述。您可以使用 subscribe 接收有关最新检测到的平面的通知，也可以使用 state 接收有关特定平面的更改的通知。

  • Anchor：虚拟对象与现实世界位置之间的链接。锚点可以附加到空间中的特定位置（使用 create）或 Trackable（使用 createAnchor）。

    • 锚点可在多个会话中重复使用。您可以使用 persist 存储锚点，使用 getPersistedAnchorUuids 枚举锚点，并使用 load 检索锚点。请确保在不再使用锚点后 unpersist 锚点。

    • 锚点可在适用于 Jetpack XR 的 ARCore 和 Jetpack SceneCore 之间互操作。您可以使用 AnchorEntity 创建锚点，或者，如果您有现有的 AnchorEntity，则可以使用 getAnchor 检索其支持锚点。

    • 使用 hitTest 提供自然的用户互动。命中测试使用 Ray 来确定与哪些内容相交，并从该位置创建 Anchor。考虑从 InputEvent 执行命中测试。

已知问题

  • 调用 unpersist 与从 getPersistedAnchorUuids 返回的结果中移除其 UUID 之间可能会有延迟。

  • create 不会验证系统是否有足够的资源来返回新锚点。创建过多的锚点可能会导致崩溃。

  • 目前不支持保留之前已保留并取消保留的锚点。

  • 支持在模拟器中使用，但其行为可能不如在实际设备上运行时稳定。特别是，对 create 的调用可能会因原生代码错误而失败，并立即终止活动。

  • 在某些情况下，使用消息“Anchor was not persisted”调用 persist 时，可能会错误地抛出 RuntimeException。在这些情况下，该函数仍会成功，并且锚点将被保留。我们建议将对 persist 的调用封装在 try 块中，以作为一种解决方法。