Thời gian chạy XR

Tài liệu tham khảo API
androidx.xr.runtime
androidx.xr.runtime.java
androidx.xr.runtime.math

Bắt đầu phiên AR hoặc 3D tuỳ chỉnh bằng thời gian chạy gốc của chúng tôi.

Bản cập nhật mới nhất	Bản phát hành ổn định	Bản phát hành dùng thử	Bản phát hành beta	Bản phát hành alpha
Ngày 25 tháng 3 năm 2026	-	-	-	1.0.0-alpha12

Khai báo phần phụ thuộc

Để thêm một phần phụ thuộc vào thời gian chạy XR, bạn phải thêm kho lưu trữ Google Maven vào dự án. Đọc nội dung Kho lưu trữ Maven của Google để biết thêm thông tin.

Thêm các phần phụ thuộc cho cấu phần phần mềm bạn cần trong tệp build.gradle cho ứng dụng hoặc mô-đun:

Groovy

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

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

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

Kotlin

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

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

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

Để biết thêm thông tin về các phần phụ thuộc, hãy xem bài viết Thêm phần phụ thuộc vào bản dựng.

Ý kiến phản hồi

Ý kiến phản hồi của bạn có thể giúp chúng tôi cải thiện Jetpack. Hãy cho chúng tôi biết nếu bạn phát hiện lỗi mới hoặc có ý tưởng cải thiện thư viện này. Vui lòng xem các lỗi hiện có trong thư viện này trước khi báo một lỗi mới. Bạn có thể thêm lượt bình chọn cho lỗi hiện có bằng cách nhấp vào nút dấu sao.

Báo lỗi mới

Xem tài liệu về Công cụ theo dõi lỗi để biết thêm thông tin.

Phiên bản 1.0

Phiên bản 1.0.0-alpha12

Ngày 25 tháng 3 năm 2026

Phát hành androidx.xr.runtime:runtime-*:1.0.0-alpha12. Phiên bản 1.0.0-alpha12 chứa các cam kết này.

Thay đổi về API

Thay đổi Config.augmentedObjectCategories từ Danh sách thành Tập hợp, (I25a64, b/487376359)
Đã xóa cờ unscaledGravityAlignedActivitySpace khỏi Session.create. ActivitySpace hiện luôn không được điều chỉnh tỷ lệ và được căn chỉnh theo trọng lực. (If6f11, b/458173423)
Thêm phương thức nạp chồng Session.create để cho phép truyền Ngữ cảnh Android cho phạm vi tài nguyên. (I7d3fe, b/415805990, b/477386334)
Thêm JvmOverloads vào FloatSize2d.to3d, Matrix3.copy, và Matrix4.copy (I69586, b/481371562)
Thêm khả năng đặt danh mục cho tính năng theo dõi AugmentedObject trong Cấu hình (I1f6e4, b/480220930)
Thêm mô-đun xr:runtime:runtime-interfaces. (I52ac6, b/461561664)

Phiên bản 1.0.0-alpha11

Ngày 25 tháng 2 năm 2026

Phát hành androidx.xr.runtime:runtime-*:1.0.0-alpha11. Phiên bản 1.0.0-alpha11 chứa các cam kết này.

Thay đổi về API

Giới hạn giao diện ConfigMode để sử dụng nội bộ (Ibfb87)
Di chuyển androidx.xr.runtime.Config.GeospatialMode sang cấp gói (Ibe682)
Di chuyển androidx.xr.runtime.Config.FaceTrackingMode sang cấp gói (Iac501)
Di chuyển androidx.xr.runtime.Config.AnchorPersistenceMode sang cấp gói (I0360f)
Di chuyển androidx.xr.runtime.Config.DepthEstimationMode sang cấp gói (I7e3e9)
Di chuyển androidx.xr.runtime.Config.DeviceTrackingMode sang cấp gói (I3aacd)
Di chuyển androidx.xr.runtime.Config.HandTrackingMode sang cấp gói (I658f3)
Di chuyển androidx.xr.runtime.Config.PlaneTrackingMode sang cấp gói (Ia251b)
Di chuyển androidx.xr.runtime.XrDevice.DisplayBlendMode sang cấp gói (I6f333)
Thêm một phương thức nhà máy để tạo XrDevice bằng Ngữ cảnh, Phiên và CoroutineContext. (I139c5)
Thêm SpatialApiVersionHelper để giúp truy vấn phiên bản thời gian chạy của Android XR có trên nền tảng. (I7c53c)
Thêm mô-đun xr:runtime:runtime-openxr (Ib42ea)

Phiên bản 1.0.0-alpha10

Ngày 28 tháng 1 năm 2026

Phát hành androidx.xr.runtime:runtime-*:1.0.0-alpha10. Phiên bản 1.0.0-alpha10 chứa các cam kết này.

Thay đổi về API

ConfigMode.HeadTrackingMode được thay thế bằng ConfigMode.DeviceTrackingMode. (le273e, b/467150206)
Xoá các phương thức toNormalized, times(float), div(float) của Quaternion. Các phương thức này là dư thừa vì tất cả Quaternion đều được chuẩn hoá tại thời điểm tạo và vì lớp này là bất biến. (l558fc, b/460210457)

Sửa lỗi

Thêm tài liệu vào Session.create minh hoạ cách tránh tạo phiên trên luồng chính của ứng dụng. (le5554, b/463687170)
Ngăn ứng dụng tạo BoundingBox có giá trị NaN. (l58c14, b/464025895)

Phiên bản 1.0.0-alpha09

Ngày 3 tháng 12 năm 2025

Phát hành androidx.xr.runtime:runtime-*:1.0.0-alpha09. Phiên bản 1.0.0-alpha09 chứa các cam kết này.

Phiên bản 1.0.0-alpha08

Ngày 19 tháng 11 năm 2025

Phát hành androidx.xr.runtime:runtime-*:1.0.0-alpha08. Phiên bản 1.0.0-alpha08 chứa các cam kết này.

Tính năng mới

Đã thêm XrDevice để cung cấp thông tin về các tính năng của thiết bị. (Ic9d1f)
Đã thêm API ConfigMode.isSupported mới để truy vấn các tính năng của phiên. (Iff7af)
Đã thêm API XrDisplay.BlendMode. (I484e4)

Thay đổi về API

Đổi tên [XrDevice.getPreferredBlendMode] thành [XrDevice.getPreferredDisplayBlendMode]. (I7e48f)

Phiên bản 1.0.0-alpha07

Ngày 22 tháng 10 năm 2025

Phát hành androidx.xr.runtime:runtime-*:1.0.0-alpha07. Phiên bản 1.0.0-alpha07 chứa các cam kết này.

Thay đổi về API

Xoá SessionConfigureConfigureNotSupported và thay thế bằng UnsupportedOperationException. (I7680f)

Phiên bản 1.0.0-alpha06

Ngày 24 tháng 9 năm 2025

Phát hành androidx.xr.runtime:runtime-*:1.0.0-alpha06. Phiên bản 1.0.0-alpha06 chứa các cam kết này.

Thay đổi về API

HandJointType đã được di chuyển từ xr:runtime:runtime sang xr:arcore:arcore. (Iadb9c, b/409058039)
Thay đổi toán tử times cho componentWiseMultiplication cho Vector2, Vector3, Vector4 để điều chỉnh theo tỷ lệ và xoá bỏ ký hiệu toán tử để có tính nhất quán với các thư viện toán học khác. Ngoài ra, xoá componentWiseDivision khỏi các lớp Vector thay vì sử dụng Vector.scale(otherVector.inverse()). (I8e1f6, b/399146447)
Thêm [unscaled] để trả về Ma trận có tỷ lệ là một. (I6381d, b/434928658)
:xr:runtime:runtime-guava sẽ bị xoá vì Coroutines.kt đã được thay thế bằng SuspendtoFutureAdapter. (I0cd3c, b/406597902)

Phiên bản 1.0.0-alpha05

Ngày 30 tháng 7 năm 2025

Phát hành androidx.xr.runtime:runtime-*:1.0.0-alpha05. Phiên bản 1.0.0-alpha05 chứa các cam kết này.

Tính năng mới

Thêm HandJointType và TrackingState. (I55880, b/334645808)
Đặt chế độ triển khai Cấu hình thành công khai. (I95860, b/334645808)
Giới thiệu các loại SessionCreateResult và SessionConfigureResult mới. (Icb8cb, b/334645808)
Thêm lớp BoundingBox mới đại diện cho một hộp giới hạn được căn chỉnh theo trục trong không gian 3D, được xác định bằng các điểm góc tối thiểu và tối đa. (Ic68c5, b/423073468)

Thay đổi về API

Đổi tên và di chuyển androidx.xr.scenecore.PixelDimensions thành androidx.xr.runtime.math.IntSize2d. Đổi tên và di chuyển androidx.xr.scenecore.Dimensions thành androidx.xr.runtime.math.FloatSize3d. Đổi tên androidx.xr.scenecore.PlaneType thành androidx.xr.scenecore.PlaneOrientation. Đổi tên androidx.xr.scenecore.PlaneSemantic thành androidx.xr.scenecore.PlaneSemanticType. (Ifd405, b/416456228)
Đã xóa lớp androidx.xr.runtime.FoV. Thay vào đó, hãy sử dụng androidx.xr.runtime.FieldOfView. (I9ae27)
Thêm một phương thức nạp chồng bổ sung cho Session.create có thể cung cấp LifecycleOwner để Phiên đính kèm. Xin lưu ý rằng bạn vẫn cần cung cấp một Hoạt động để sở hữu tài nguyên và LifecycleOwner phải được đặt trong phạm vi Hoạt động. (I1690b)
Đổi tên FakeRuntimeAnchor.anchorsCreated thành anchorsCreatedCount (I96df9, b/424441218)
Các giá trị *Mode của Cấu hình đã được đổi tên để phản ánh hành vi của chúng. (I6d247, b/414648065)
Các dự án được phát hành bằng Kotlin 2.0 yêu cầu sử dụng KGP 2.0.0 trở lên (Idb6b5, b/344563182)
Các API liên quan đến chuỗi tệp kê khai đã được di chuyển từ :xr:runtime:runtime sang :xr:runtime:runtime-manifest. Tên gói đã thay đổi từ androidx.xr.runtime thành androidx.xr.runtime.manifest. (I610ad, b/418800249)
Session.resume(), Session.pause() và Session.destroy() đã bị xoá khỏi bề mặt API. Phiên không còn là LifecycleOwner. Vòng đời của Phiên hiện sẽ được đính kèm vào vòng đời của Hoạt động được truyền trong Session.create(). (I28a03)
Thư viện này hiện sử dụng chú thích thuộc tính rỗng JSpecify, là loại sử dụng. Nhà phát triển Kotlin nên sử dụng đối số trình biên dịch sau để thực thi việc sử dụng chính xác: -Xjspecify-annotations=strict (đây là giá trị mặc định bắt đầu từ phiên bản 2.1.0 của trình biên dịch Kotlin) (Ia8420, b/326456246)
Cấu phần phần mềm Thời gian chạy chính (:xr:runtime:runtime) sẽ chỉ chứa các API không đồng bộ theo kiểu Kolin. Nhà phát triển Java có thể phụ thuộc vào :xr:runtime:runtime-guava để truy cập vào các API tương thích. (I05d4a, b/426639315)
Cấu phần phần mềm Thời gian chạy chính (:xr:runtime:runtime) sẽ chỉ chứa các API không đồng bộ theo kiểu Kotlin. Nhà phát triển Java có thể phụ thuộc vào thư viện xr:runtime:runtime-rxjava3 để truy cập vào các API tương thích. (I64122, b/426639775)
Di chuyển Coroutine sang :xr:runtime:runtime-guava và Luồng sang :xr:runtime:runtime-rxjava3. (I60ae9)
Session.create và Session.configure hiện gửi SecurityException khi chưa cấp đủ quyền thay vì trả về SessionCreatePermissionsNotGranted hoặc SessionConfigurePermissionsNotGranted. (I7c488, b/430651879)

Phiên bản 1.0.0-alpha04

Ngày 7 tháng 5 năm 2025

Phát hành androidx.xr.runtime:runtime:1.0.0-alpha04, androidx.xr.runtime:runtime-openxr:1.0.0-alpha04 và androidx.xr.runtime:runtime-testing:1.0.0-alpha04. Phiên bản 1.0.0-alpha04 chứa các cam kết này.

Tính năng mới

Phiên hiện triển khai androidx.lifecycle.LifecycleOwner để có khả năng tương tác nhiều hơn với các mô hình vòng đời Android hiện có.
Chuỗi tệp kê khai cho Android XR được chỉ định và ghi lại tại đây.
Đã thêm các phương thức mở rộng Gọi lại khả năng hiển thị không gian để theo dõi thời điểm nội dung cảnh di chuyển vào hoặc ra khỏi trường nhìn của người dùng.
Đã thêm phiên bản mã giả lập của JxrPlatformAdapter (và tất cả các lớp liên quan).
Phiên sẽ được sử dụng trong cả SceneCore và Thời gian chạy thay vì Phiên trong SceneCore.
Đã thêm ActivityPose.hitTest, cho phép hitTest đối với nội dung ảo.
Hiện đã hỗ trợ việc chỉ định nhiều cách triển khai Thời gian chạy tại thời điểm biên dịch. Chỉ một cách triển khai sẽ được tải tại thời điểm thực thi dựa trên tập tính chất của thiết bị hiện tại.
Đã thêm loại Thành phần mới SpatialPointerComponent, cho phép ứng dụng chỉ định biểu tượng được kết xuất cho con trỏ hoặc tắt biểu tượng. Hiện tại, Thành phần này chỉ có thể được đính kèm vào các thực thể PanelEntity.

Thay đổi về API

Đặt chế độ triển khai Cấu hình thành công khai. (I95860)
Thêm HandJointType và TrackingState. (I55880)
Các dự án được phát hành bằng Kotlin 2.0 yêu cầu sử dụng KGP 2.0.0 trở lên (Idb6b5)
Hand.isActive (boolean) đã được thay đổi thành Hand.trackingState. Cách triển khai OpenXR đã được sửa đổi cho phù hợp.
Yêu cầu về quyền android.permission.SCENE_UNDERSTANDING trong Session.configure đã được thay đổi thành android.permission.SCENE_UNDERSTANDING_COARSE.
LifecycleManager.configure được triển khai và hiện truyền một đối tượng Config chứa một thuộc tính cho mỗi tính năng thời gian chạy có thể định cấu hình.
Giờ đây, bạn có thể gọi Session.configure bằng Config để định cấu hình các tính năng thời gian chạy hiện có.
Session.create hiện hỗ trợ việc truyền CoroutineContext thay vì CoroutineDispatcher.
Session.create hỗ trợ tải ARCore cho Jetpack XR và/hoặc SceneCore. Bạn phải cung cấp ít nhất một phiên bản (có các phiên bản thử nghiệm).
FakePerceptionManager gửi một AnchorInvalidUuidException khi một UUID không hợp lệ được truyền đến Anchor.load và Anchor.unpersist.
CoreState không còn là một lớp dữ liệu.

Sửa lỗi

Đã sửa cấu hình Proguard thời gian chạy.

Phiên bản 1.0.0-alpha03

Ngày 26 tháng 2 năm 2025

Phát hành androidx.xr.runtime:runtime:1.0.0-alpha03, androidx.xr.runtime:runtime-openxr:1.0.0-alpha03 và androidx.xr.runtime:runtime-testing:1.0.0-alpha03 mà không có thay đổi đáng kể nào kể từ bản alpha gần đây nhất. Phiên bản 1.0.0-alpha03 chứa các cam kết này.

Phiên bản 1.0.0-alpha02

Ngày 12 tháng 2 năm 2025

Phát hành androidx.xr.runtime:runtime:1.0.0-alpha02, androidx.xr.runtime:runtime-openxr:1.0.0-alpha02 và androidx.xr.runtime:runtime-testing:1.0.0-alpha02. Phiên bản 1.0.0-alpha02 chứa các cam kết này.

Các thay đổi có thể gây lỗi và thay đổi về hành vi

Các hàm thời gian chạy OpenXR trả về một Neo hiện gửi AnchorResourcesExhaustedException nếu gặp phải mã lỗi thông báo rằng đã đạt đến giới hạn tài nguyên OpenXR.
Giờ đây, bạn phải có quyền android.permission.HAND_TRACKING cho Session.create và Session.resume.

Tính năng mới

Đã thêm tính năng hỗ trợ theo dõi cử động của tay.

Sửa lỗi

Việc tạo neo ổn định hơn khi chạy trên trình mô phỏng

Phiên bản 1.0.0-alpha01

Ngày 12 tháng 12 năm 2024

Phát hành androidx.xr.runtime:runtime-* 1.0.0-alpha01.

Các tính năng của bản phát hành đầu tiên

Bản phát hành đầu tiên của Thời gian chạy Jetpack XR. Thư viện này chứa các phần chức năng cơ bản cho bộ thư viện Jetpack XR. Trong đó có tính năng phát hiện, quản lý vòng đời, định cấu hình và nhiều tính năng khác. Thư viện Thời gian chạy cung cấp nhiều biến thể (ví dụ: runtime-openxr hoặc runtime-testing) tuỳ thuộc vào nền tảng thực thi. Ngoài ra, thư viện này cung cấp các khái niệm trừu tượng toán học cơ bản như Vector3 và Matrix4 được sử dụng trên toàn bộ bề mặt API Jetpack XR.

Session: Cung cấp cho bạn các biện pháp kiểm soát chi tiết đối với hệ thống XR, bao gồm cả việc quyết định thời điểm thực thi và không thực thi quá trình xử lý cũng như cấu hình tổng thể. Đây cũng là handle mà bạn sẽ sử dụng trên tất cả các API khác để mở khoá các tính năng hệ thống cơ bản.
Pose: Một vị trí trong hệ toạ độ tuỳ ý có vị trí và hướng liên kết với vị trí đó. Bạn sẽ sử dụng lớp này để truyền đạt vị trí của các đối tượng bằng ARCore cho Jetpack XR và Jetpack SceneCore.

Lỗi đã biết

configure hiện là một thao tác không có tác dụng. Các bản phát hành trong tương lai sẽ thêm các chế độ cài đặt mới mà bạn có thể dùng để kiểm soát hành vi của Session.