ARCore for Jetpack XR

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

声明依赖项

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

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

Groovy

dependencies {
    implementation "androidx.xr.arcore:arcore:1.0.0-rc01"
}

Kotlin

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

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

反馈

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

创建新问题

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

版本 1.0

版本 1.0.0-rc01

2026 年 9 月 9 日

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

版本 1.0.0-beta02

2026 年 8 月 12 日

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

bug 修复

  • 修复了 OpenXR 锚点持久性中的并发问题。(I15c8b)
  • 在更多类中实现了 toString() 以进行调试。(I587e8)

版本 1.0.0-beta01

2026 年 7 月 15 日

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

API 变更

  • 更新了可调整大小的修饰符，以使用一个 ResizePolicy 而不是两个修饰符（I7fb0f、b/496257436、b/519672992）
  • 添加了具有 movePolicy 参数的可移动重载，并废弃了 transformingMovable 和 movable（Ic88c1、b/481781189）
  • 从公共 API surface 中移除了 TrackingState.TRACKING_DEGRADED，并将运行时降级状态映射到 PAUSED。更新了 TrackingState，以使用枚举而非 int 值进行字符串转换和运行时转换。（I3eb5b、b/524326338）
  • 将 Session.create 转换为挂起函数。(I5d27f)
  • 废弃了 ProjectedPermissionsResultContract（I141d5、b/515699436）
  • 已将 AnchorEntity 更新为 AnchorSpace（Ifa95e、b/513619219）

版本 1.0.0-alpha15

2026 年 6 月 17 日

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

API 变更

  • 已移除HitResult.createAnchor。如果结果的可跟踪对象是 Anchorable，开发者可以通过向 Anchorable 的 createAnchor 函数提供命中位置来创建表示 HitResult 的锚点。(Ia851e)
  • 已移除AnchorUnsupportedObject。JXR ARCore 运行时不再抛出此异常。(Ia851e)
  • androidx.xr.arcore.Anchor 和 androidx.xr.arcore.ArDevice 现在实现了 androidx.xr.arcore.Trackable。(I57b65)
  • Depth.left、Depth.right 和 Depth.mono 现在不可为 null (I1fc5e)
  • Face.getUserFace 现在不可为 null (I0eac1)
  • RenderViewpoint.left、RenderViewpoint.right、RenderViewpoint.mono 现在不可为 null (Icf7fa)
  • Hand.left 和 Hand.right 不再可为 null (Icef37)
  • 添加了 QrCode API (Ia0bbe)

版本 1.0.0-alpha14

2026 年 5 月 19 日

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

API 变更

  • 弃用 GeospatialMode.VPS_AND_GPS，改用 GeospatialMode.SPATIAL，并推出一种新的低功耗追踪模式 GeospatialMode.INERTIAL，该模式仅使用 IMU 和 GPS。(I1e6cd)
  • 自定义锚点异常类：AnchorInvalidUuidException、AnchorNotAuthorizedException、AnchorUnsupportedLocationException、AnchorRuntimeFailureException 和 AnchorUnsupportedObjectException 现在是 RuntimeException 实例，不打算进行检查。(I9356e)
  • 添加了 ArCoreTestRule API，包括 TestArDevice、TestAugmentableObject、TestDepthMap、TestEye、TestFace、TestGeospatial、TestHand、TestPlane、TestRenderViewpoint 和 TestTrackable (I0ad3c)
  • 移除了 AnchorLoadInvalidUuid、AnchorCreateUnsupportedObject、AnchorCreateUnsupportedLocation 和 AnchorCreateNotAuthorized。所有这些错误现在都是运行时异常。移除了 AnchorCreateIllegalState。在大多数情况下，此方法已被 AnchorCreateTrackingUnavailable 取代。添加了 AnchorException 和派生类 AnchorInvalidUuidException、AnchorNotAuthorizedException、AnchorUnsupportedLocationException、AnchorRuntimeFailureException 和 AnchorUnsupportedObjectException。(I4c4dd)

外部贡献

  • 添加了用于自定义标记跟踪的 AugmentedImage API (I0cf09)

版本 1.0.0-alpha13

2026 年 5 月 6 日

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

API 变更

  • TrackingState 和 VpsAvailabilityResult 已移至 androidx.xr.arcore package，androidx.xr.runtime 中的类型现已弃用。（Ic7930、b/480462213）
  • Plane.Type 已重命名为 PlaneType。（I8c90c、b/482675376）
  • Hand.HandSide 已重命名为 HandSide。（Ica562、b/482675376）
  • Plane.Label 已重命名为 PlaneLabel。（Ic6b67、b/482675376）
  • Geospatial.Surface 已重命名为 GeospatialSurface。（I1a8be、b/482675376）
  • 已将 Geospatial.State 重命名为 GeospatialState。（I203fa、b/482675376）
  • 将 NativeData API 移至 xr:runtime:runtime 库。（I87954、b/494251500）
  • Session.create 和 Session.configure 现在是非详尽的，需要在 when 语句中添加 else 子句。（I9885e、b/495805998、b/495805998）
  • 已弃用 androidx.xr.runtime.FieldOfView。请改用 androidx.xr.runtime.math.FieldOfView。（Ia01a0、b/480233045）
  • 将 Orbiter 更改为使用 OrbiterAnchorPoint + VolumeOffset 或 OrbiterPoseProvider，而不是位置、偏移量、offsetType、对齐方式和海拔高度。还移除了 shouldRenderInNonSpatial 参数。如果开发者不希望轨道飞行器在非空间中渲染，则应将轨道飞行器封装在 if 语句中并检查 SpatialCapabilities。（I9fbb3、b/462428503）
  • 添加了可移动的修饰符。这些修饰符目前适用于 SpatialPanels 和 SpatialExternalSurface。很快，SpatialGltfModels 也将支持这些功能。不过，我们的目标是让所有 SubspaceComposables 都能够很好地支持这些功能。（I9a3cd、b/479530787、b/478935063、b/478935063）
  • 开发者应遵循ArDevice.state流程来监控State.trackingState，并根据跟踪保真度相应地调整应用的渲染或警告。（Ic00f0、b/445466590）
  • 重命名了 HandJointType 枚举值。（Ifbc83、b/482670596）
  • 重命名了 FaceConfidenceRegion 常量。（Ia62d5、b/482670596）
  • 重命名了 FaceBlendShapeType 常量。（I33b8b、b/482670596）
  • 添加了 CreatePoseFromGeospatialPoseErrorInternal 和 CreateGeospatialPoseFromPoseErrorInternal。（I4bcf1、b/482666615）
  • 将 DeviceTrackingMode.LAST_KNOWN 重命名为 SPATIAL_LAST_KNOWN（具有已弃用的回退），添加了用于 3DoF 跟踪的 INERTIAL_LAST_KNOWN，并将 TRACKING_DEGRADED 添加到了 TrackingState。（Ie661c、b/445466590）
  • 已废弃 GroupEntity。如需仅具有基本实体功能的实体，请调用 Entity.create，该方法将返回实体接口。（I4c450、b/473867483）
  • 添加了 XrLog API。将 XrLog.isEnabled 设置为 true 可在 JetpackXR 中启用日志记录，并使用 XrLog.Level 设置日志级别。（I76a1f、b/463460895、b/487378441）

bug 修复

版本 1.0.0-alpha12

2026 年 3 月 25 日

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

API 变更

  • 将 Config.augmentedObjectCategories 从 List 更改为 Set。（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）
  • ARCore for Jetpack XR 现在使用 XR Runtime 日志记录机制。如需了解详情，请访问 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 中包含这些提交内容。

新功能

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

版本 1.0.0-alpha07

October 22, 2025

发布了 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)
  • 将 HandJointType 枚举重命名为以 HAND_JOINT_TYPE_ 为前缀。(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)
  • 添加了地理空间检查 VPS 可用性 API (I58573)
  • 为 checkVpsAvailability 添加了 ARCore API (Idbded)
  • 为供 Java 开发者使用，向 :xr:arcore:arcore-rxjava3 添加了 stateFlowable 扩展函数。（I083aa、b/427247794）

API 变更

  • 已重命名配置 *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)
  • 为供 Java 开发者使用，向 :xr:arcore:arcore-rxjava3 添加了 subscribeAsFlowable 扩展函数。（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 移至运行时。
  • 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。

初始版本的功能

ARCore for Jetpack XR 库的灵感源自现有的 ARCore 库，可提供将数字内容与现实世界相融合的功能。该库包含动作追踪、持久锚点、命中测试和平面识别功能，并提供语义标签（例如地面、墙壁和桌面）。如需详细了解如何将 ARCore 用于 Jetpack XR，请参阅开发者指南。

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

  • Plane：使用平面来了解周围的世界。每个平面都有一个 Label，用于从语义上描述该平面。您可以使用 subscribe 接收有关最新检测到的飞机的通知，也可以使用 state 接收有关特定飞机发生变化的通知。

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

    • 锚点可在多个会话中重复使用。您可以使用 persist 存储它们，使用 getPersistedAnchorUuids 枚举它们，并使用 load 检索它们。请确保在不再使用这些资源时将其unpersist。

    • 锚点可在 ARCore for Jetpack XR 和 Jetpack SceneCore 之间互操作。您可以使用锚点创建 AnchorEntity，也可以使用 getAnchor 检索现有 AnchorEntity 的支持锚点。

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

已知问题

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

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

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

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

  • 在某些情况下，使用“Anchor was not persisted”消息调用 persist 时，可能会错误地抛出 RuntimeException。在这些情况下，该函数仍会成功执行，并且锚点会被持久化。我们建议将对 persist 的调用封装在 try 块中，以解决此问题。