XR 執行階段

使用原生執行階段啟動自訂 AR 或 3D 工作階段。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2026 年 6 月 17 日 - - - 1.0.0-alpha15

宣告依附元件

如要新增 XR 執行階段的依附元件，必須將 Google Maven 存放區新增至專案。詳情請參閱「 Google 的 Maven 存放區」。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

dependencies {
    implementation "androidx.xr.runtime:runtime:1.0.0-alpha15"

    // Use in environments that do not support OpenXR
    testImplementation "androidx.xr.runtime:runtime-testing:1.0.0-alpha15"
}

Kotlin

dependencies {
    implementation("androidx.xr.runtime:runtime:1.0.0-alpha15")

    // Use in environments that do not support OpenXR
    testImplementation("androidx.xr.runtime:runtime-testing:1.0.0-alpha15")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.0 版本

1.0.0-alpha15 版本

2026 年 6 月 17 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha15。1.0.0-alpha15 版包含這些修訂項目。

API 變更

  • 新增 isProjectedServiceAvailable() 的測試 API (I44ba1)
  • 在新的 @ExperimentalInertialTrackingApi 註解下，將 DeviceTrackingMode.INERTIAL 公開為實驗性 API。(Ic3df3)
  • 新增了 Config.Builder。應用程式可以在建構工具物件上呼叫設定器函式，然後呼叫 Builder.build，藉此建立自訂設定。(I13142)
  • 已移除 androidx.xr.runtime.FieldOfView。應用程式應改用 androidx.xr.runtime.math.FieldOfView。(I621ef)
  • 現在必須在 @WorkerThread 上執行 Session.create。(I2169e)
  • 在 XrDevice 中新增 isProjectedServiceAvailable() (I507e9)
  • 將 DeviceTrackingMode.SPATIAL_LAST_KNOWN 重新命名為 DeviceTrackingMode.SPATIAL，並將 DeviceTrackingMode.INERTIAL_LAST_KNOWN 重新命名為 DeviceTrackingMode.INERTIAL (I96f8b)
  • Vector3.angleBetween 和 Vector4.angleBetween 現在會傳回角度，而不是弧度。(Ica8bc)
  • 新增 QrCode API (Ia0bbe)

1.0.0-alpha14 版本

2026 年 5 月 19 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha14。1.0.0-alpha14 版包含這些修訂項目。

API 變更

  • 我們將淘汰 GeospatialMode.VPS_AND_GPS，改用 GeospatialMode.SPATIAL，並推出新的低耗電追蹤模式 GeospatialMode.INERTIAL，這個模式只會使用 IMU 和 GPS。(I1e6cd)
  • 移除 androidx.xr.runtime.FieldOfView 的淘汰標記。將 androidx.xr.runtime.math.FieldOfView 設為 androidx.xr.runtime.FieldOfView 的型別別名，為後者在下一個版本中移除做準備。如果用戶端目前使用 androidx.xr.runtime 版本，就必須遷移至 androidx.xr.runtime.math 版本。(I6ce15)
  • 新增 PreviewProjectedApi 註解 (Ic49f6)
  • 已移除 AugmentedObjectCategory.allSupported (I08656)
  • 在 XrDevice 中新增 API，判斷裝置是否支援手勢追蹤、眼動追蹤、深度估算、地理空間和算繪。(I00696)
  • Session.getNativeData 已替換為 XrDevice.getNativeInstanceData 和 Session.getNativeSessionData。(Ieb077)
  • 以 @PreviewSpatialApi 為 DeviceTrackingMode.INERTIAL_LAST_KNOWN 加註。(I99868)
  • 新增 XrDeviceTestRule，以便在單元測試中使用。(I87584)
  • 新增 CATEGORY_XR_PROJECTED_LAUNCHER 後，資訊清單檔案會使用這個常數，指出系統應將活動探索為啟動器。(Ia3069)

外部貢獻

  • 將 AugmentedImageMode 新增至 Config API (I0cf09)

1.0.0-alpha13 版

2026 年 5 月 6 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha13。1.0.0-alpha13 版包含這些修訂項目。

API 變更

  • TrackingState 和 VpsAvailabilityResult 已移至 androidx.xr.arcore package，且 androidx.xr.runtime 中的型別現已淘汰。(Ic7930、b/480462213)
  • Session.getNativeData() 現在定義了 xr:runtime:runtime 模組，並為 OpenXR 支援的執行階段提供 [nativeFunctionTablePointer]。(Ifa862)
  • 已將 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)
  • 「Matrix4.pose」已重新命名為「Matrix4.toPose()」。pose 屬性現已淘汰。(I329b4、b/493383490)
  • 新增 XrServiceAvailability API (If379e、b/493558010)
  • 新增 ExperimentalXrServiceAvailabilityApi 註解 (Icab49、b/491069725)
  • 移除 @PreviewSpatialApi 的後置字元 (If5242、b/491939311)
  • 已將 DeviceTrackingMode.LAST_KNOWN 重新命名為 SPATIAL_LAST_KNOWN (並提供已淘汰的備用選項)，新增 INERTIAL_LAST_KNOWN 以進行 3DoF 追蹤，並將 TRACKING_DEGRADED 新增至 TrackingState。(Ie661c、b/445466590)
  • 新增 XrLog API。將 XrLog.isEnabled 設為 true，即可在 JetpackXR 中啟用記錄功能，並使用 [XrLog.Level] 設定記錄層級。(I76a1f、b/463460895、b/487378441)
  • 新增 DISPLAY_CATEGORY_XR_PROJECTED，這個常數會用於資訊清單檔案，指出活動適用於 XR 投影螢幕 (I26d8b)

1.0.0-alpha12 版

2026 年 3 月 25 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha12。1.0.0-alpha12 版包含這些修訂項目。

API 變更

  • 將 Config.augmentedObjectCategories 從 List 變更為 Set (I25a64、b/487376359)
  • 已從 Session.create 移除 unscaledGravityAlignedActivitySpace 旗標。ActivitySpace 現在一律不會縮放，且會對齊重力。(If6f11、b/458173423)
  • 新增 Session.create 超載，可傳遞 Android Context 以進行資源範圍設定。(I7d3fe、b/415805990、b/477386334)
  • 將 JvmOverloads 新增至 FloatSize2d.to3d、Matrix3.copy 和 Matrix4.copy (I69586、b/481371562)
  • 新增在設定中設定 AugmentedObject 追蹤類別的功能 (I1f6e4、b/480220930)
  • 新增了 xr:runtime:runtime-interfaces 模組。(I52ac6、b/461561664)

1.0.0-alpha11 版本

2026 年 2 月 25 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha11。1.0.0-alpha11 版包含這些修訂項目。

API 變更

  • 將 ConfigMode 介面限制為內部使用 (Ibfb87)
  • 已將 androidx.xr.runtime.Config.GeospatialMode 移至套件層級 (Ibe682)
  • 已將 androidx.xr.runtime.Config.FaceTrackingMode 移至套件層級 (Iac501)
  • 已將 androidx.xr.runtime.Config.AnchorPersistenceMode 移至套件層級 (I0360f)
  • 已將 androidx.xr.runtime.Config.DepthEstimationMode 移至套件層級 (I7e3e9)
  • 已將 androidx.xr.runtime.Config.DeviceTrackingMode 移至套件層級 (I3aacd)
  • 已將 androidx.xr.runtime.Config.HandTrackingMode 移至套件層級 (I658f3)
  • 已將 androidx.xr.runtime.Config.PlaneTrackingMode 移至套件層級 (Ia251b)
  • 已將 androidx.xr.runtime.XrDevice.DisplayBlendMode 移至套件層級 (I6f333)
  • 新增工廠方法，可使用 Context、Session 和 CoroutineContext 建立 XrDevice。(I139c5)
  • 新增 SpatialApiVersionHelper，協助查詢平台可用的 Android XR 執行階段版本。(I7c53c)
  • 新增 xr:runtime:runtime-openxr 模組 (Ib42ea)

1.0.0-alpha10 版本

2026 年 1 月 28 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha10。1.0.0-alpha10 版包含這些修訂項目。

API 變更

  • ConfigMode.HeadTrackingMode 已改為 ConfigMode.DeviceTrackingMode。(le273e、b/467150206)
  • 已移除 Quaternion 的 toNormalized、times(float)、div(float) 方法。由於所有四元數都會在建構時正規化，且類別不可變動，因此這些方法是多餘的。(l558fc、b/460210457)

修正錯誤

  • 新增Session.create說明文件，說明如何避免在應用程式的主執行緒上建立工作階段。(le5554、b/463687170)
  • 防止應用程式建立具有 NaN 值的 BoundingBox。(l58c14、b/464025895)

1.0.0-alpha09 版本

2025 年 12 月 3 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha09。1.0.0-alpha09 版包含這些修訂項目。

1.0.0-alpha08 版本

2025 年 11 月 19 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha08。1.0.0-alpha08 版包含這些修訂項目。

新功能

  • 新增了 XrDevice，提供裝置功能相關資訊。(Ic9d1f)
  • 新增 ConfigMode.isSupported API，用於查詢工作階段功能。(Iff7af)
  • 新增 XrDisplay.BlendMode API。(I484e4)

API 變更

  • 已將 [XrDevice.getPreferredBlendMode] 重新命名為 [XrDevice.getPreferredDisplayBlendMode]。(I7e48f)

1.0.0-alpha07 版本

October 22, 2025

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha07。1.0.0-alpha07 版包含這些修訂項目。

API 變更

  • 移除 SessionConfigureConfigureNotSupported，並替換為 UnsupportedOperationException。(I7680f)

1.0.0-alpha06 版本

2025 年 9 月 24 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha06。1.0.0-alpha06 版包含這些修訂項目。

API 變更

  • HandJointType 已從 xr:runtime:runtime 移至 xr:arcore:arcore。(Iadb9c、b/409058039)
  • 將 componentWiseMultiplication 的時間運算子變更為 Vector2、Vector3、Vector4，以便進行縮放，並移除運算子符號，確保與其他數學程式庫一致。此外，我們也從 Vector 類別中移除 componentWiseDivision，改用 Vector.scale(otherVector.inverse())。(I8e1f6、b/399146447)
  • 新增 [unscaled] 即可傳回比例為一的 Matrix。(I6381d、b/434928658)
  • :xr:runtime:runtime-guava 將移除，因為 Coroutines.kt 已改為 SuspendtoFutureAdapter。(I0cd3c、b/406597902)

1.0.0-alpha05 版本

2025 年 7 月 30 日

發布 androidx.xr.runtime:runtime-*:1.0.0-alpha05。1.0.0-alpha05 版包含這些修訂項目。

新功能

  • 新增 HandJointType 和 TrackingState。(I55880、b/334645808)
  • 將 Config 實作設為公開。(I95860、b/334645808)
  • 推出新的 SessionCreateResult 和 SessionConfigureResult 類型。(Icb8cb、b/334645808)
  • 新增 BoundingBox 類別，代表 3D 空間中與軸對齊的定界框，由最小和最大角點定義。(Ic68c5、b/423073468)

API 變更

  • 已將 androidx.xr.scenecore.PixelDimensions 重新命名為 androidx.xr.runtime.math.IntSize2d，並移至該位置。已將 androidx.xr.scenecore.Dimensions 重新命名為 androidx.xr.runtime.math.FloatSize3d，並移至該位置。androidx.xr.scenecore.PlaneType 已重新命名為 androidx.xr.scenecore.PlaneOrientation。androidx.xr.scenecore.PlaneSemantic 已重新命名為 androidx.xr.scenecore.PlaneSemanticType。(Ifd405、b/416456228)
  • 已移除 androidx.xr.runtime.FoV 類別。請改用 androidx.xr.runtime.FieldOfView。(I9ae27)
  • 新增 Session.create 的額外超載，可為要附加的 Session 提供 LifecycleOwner。請注意，您仍須提供活動，才能取得資源擁有權，且 LifecycleOwner 必須限定在活動範圍內。(I1690b)
  • 已將 FakeRuntimeAnchor.anchorsCreated 重新命名為 anchorsCreatedCount (I96df9、b/424441218)
  • 設定 *Mode 值已重新命名，以反映其行為。(I6d247、b/414648065)
  • 使用 Kotlin 2.0 發布的專案必須使用 KGP 2.0.0 以上版本 (Idb6b5、b/344563182)
  • 與資訊清單字串相關的 API 已從 :xr:runtime:runtime 遷移至 :xr:runtime:runtime-manifest。套件名稱已從「androidx.xr.runtime」變更為「androidx.xr.runtime.manifest」。(I610ad、b/418800249)
  • Session.resume()、Session.pause() 和 Session.destroy() 已從 API 介面中移除。工作階段不再是 LifecycleOwner。現在，Session 的生命週期會附加至 Session.create() 中傳遞的 Activity 生命週期。(I28a03)
  • 這個程式庫現在使用 JSpecify 空值註解，這些註解屬於型別用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版的預設值) (Ia8420、b/326456246)
  • 主要執行階段構件 (:xr:runtime:runtime) 只會包含 Kotlin 樣式的非同步 API。Java 開發人員可以依賴 :xr:runtime:runtime-guava 存取相容的 API。(I05d4a、b/426639315)
  • 主要執行階段構件 (:xr:runtime:runtime) 只會包含 Kotlin 樣式的非同步 API。Java 開發人員可以依附 xr:runtime:runtime-rxjava3 程式庫來存取相容的 API。(I64122、b/426639775)
  • 將協同程式移至 :xr:runtime:runtime-guava，並將 Flow 移至 :xr:runtime:runtime-rxjava3。(I60ae9)
  • 如果未授予足夠的權限，Session.create 和 Session.configure 現在會擲回 SecurityException，而不是傳回 SessionCreatePermissionsNotGranted 或 SessionConfigurePermissionsNotGranted。(I7c488、b/430651879)

1.0.0-alpha04 版本

2025 年 5 月 7 日

發布 androidx.xr.runtime:runtime:1.0.0-alpha04、androidx.xr.runtime:runtime-openxr:1.0.0-alpha04 和 androidx.xr.runtime:runtime-testing:1.0.0-alpha04。1.0.0-alpha04 版包含這些修訂項目。

新功能

  • Session 現在會實作 androidx.lifecycle.LifecycleOwner，以便與現有的 Android 生命週期範例進行更多互通性。
  • Android XR 的資訊清單字串指定和記錄位置請參閱這裡。
  • 新增 Spatial Visibility Callback 擴充方法，用於監控場景內容在使用者視野內或視野外的移動情形。
  • 新增 JxrPlatformAdapter 的虛設常式版本 (和所有相關類別)。
  • 「工作階段」會同時用於 SceneCore 和 Runtime，而非 SceneCore 中的「工作階段」。
  • 已新增 ActivityPose.hitTest，可針對虛擬內容進行 hitTest。
  • 現在支援在編譯時間指定多個執行階段實作項目。執行時，系統會根據目前裝置的功能集載入其中一個。
  • 新增 SpatialPointerComponent 元件類型，讓用戶指定指標的顯示圖示，或停用圖示。目前這個元件只能附加至 PanelEntity 個執行個體。

API 變更

  • 將 Config 實作設為公開。(I95860)
  • 新增 HandJointType 和 TrackingState。(I55880)
  • 以 Kotlin 2.0 發布的專案必須使用 KGP 2.0.0 以上版本 (Idb6b5)
  • 「Hand.isActive (boolean)」已變更為「Hand.trackingState」。OpenXR 實作方式已相應修改。
  • Session.configure 中的 android.permission.SCENE_UNDERSTANDING 權限規定已變更為 android.permission.SCENE_UNDERSTANDING_COARSE。
  • LifecycleManager.configure 已實作，現在會傳遞 Config 物件，其中包含每個可設定的執行階段功能的屬性。
  • 現在可以透過 Config 呼叫 Session.configure，設定可用的執行階段功能。
  • Session.create 現在支援傳遞 CoroutineContext，而非 CoroutineDispatcher。
  • Session.create 支援載入 Jetpack XR 和/或 SceneCore 的 ARCore。至少須提供一個 (可使用測試版)。
  • 如果傳遞無效的 UUID 給 Anchor.load 和 Anchor.unpersist，FakePerceptionManager 會擲回 AnchorInvalidUuidException。
  • CoreState 不再是資料類別。

修正錯誤

  • 修正執行階段 ProGuard 設定。

1.0.0-alpha03 版本

2025 年 2 月 26 日

發布 androidx.xr.runtime:runtime:1.0.0-alpha03、androidx.xr.runtime:runtime-openxr:1.0.0-alpha03 和 androidx.xr.runtime:runtime-testing:1.0.0-alpha03，但自上次 Alpha 版以來沒有重大異動。1.0.0-alpha03 版包含這些修訂項目。

1.0.0-alpha02 版

2025 年 2 月 12 日

發布 androidx.xr.runtime:runtime:1.0.0-alpha02、androidx.xr.runtime:runtime-openxr:1.0.0-alpha02 和 androidx.xr.runtime:runtime-testing:1.0.0-alpha02。1.0.0-alpha02 版包含這些修訂項目。

破壞性變更和行為變更

  • 如果 OpenXR 執行階段函式傳回 Anchor，且遇到通知已達 OpenXR 資源限制的錯誤碼，現在會擲回 AnchorResourcesExhaustedException。
  • Session.create 和 Session.resume 現在必須提供 android.permission.HAND_TRACKING 權限。

新功能

  • 新增手勢追蹤支援。

修正錯誤

  • 在模擬器上執行時，建立錨點的穩定性更高

1.0.0-alpha01 版

2024 年 12 月 12 日

發布 androidx.xr.runtime:runtime-* 1.0.0-alpha01。

初始版本的功能

Jetpack XR Runtime 的初始版本。這個程式庫包含 Jetpack XR 程式庫套件的基本功能。包括功能探索、生命週期管理、設定等。視執行平台而定，執行階段程式庫會提供不同變體 (例如 runtime-openxr 或 runtime-testing)。此外，這個程式庫還提供基本數學抽象概念，例如 Vector3 和 Matrix4，這些概念會用於整個 Jetpack XR API 介面。

  • Session：可精細控管 XR 系統，包括決定何時執行處理作業，以及整體設定。您也會使用這個控制代碼，透過所有其他 API 解鎖基礎系統功能。

  • Pose：任意座標系統中的位置，具有相關聯的位置和方向。您將使用這個類別，透過 Jetpack XR 和 Jetpack SceneCore 與 ARCore 通訊，傳達物件的位置。

已知問題

  • configure 目前為無運算元。日後發布的版本會新增設定，供您控管 Session 的行為。