Jetpack Compose cho XR

Jetpack Compose cho XR

Hướng dẫn sử dụng  Mã mẫu  Lớp học lập trình

Tài liệu tham khảo API
androidx.xr.compose.platform
androidx.xr.compose.spatial
androidx.xr.compose.subspace
androidx.xr.compose.subspace.layout
androidx.xr.compose.subspace.node
androidx.xr.compose.unit

Tạo bố cục giao diện người dùng không gian theo cách khai báo để tận dụng các tính năng không gian của Android XR.

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 7 tháng 5 năm 2025	-	-	-	1.0.0-alpha04

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

Để thêm một phần phụ thuộc trên XR Compose, 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:

GroovyKotlin Thêm

dependencies {
    implementation "androidx.xr.compose:compose:1.0.0-alpha04"

    // Use to write unit tests
    testImplementation "androidx.xr.compose:compose-testing:1.0.0-alpha04"
}

dependencies {
    implementation("androidx.xr.compose:compose:1.0.0-alpha04")

    // Use to write unit tests
    testImplementation("androidx.xr.compose:compose-testing:1.0.0-alpha04")
}

Để 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-alpha04

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

Phát hành androidx.xr.compose:compose:1.0.0-alpha04 và androidx.xr.compose:compose-testing:1.0.0-alpha04. Phiên bản 1.0.0-alpha04 bao gồm các thay đổi sau.

Lưu ý: Bạn cần có Trình mô phỏng Android phiên bản 35.6.7 trở lên để sử dụng phiên bản thư viện này.

Tính năng mới

• Thêm giao diện CompositionLocalConsumerSubspaceModifierNode để cho phép các loại SubspaceModifier tuỳ chỉnh truy cập vào các giá trị cục bộ của thành phần.
• Thêm một API SpatialPanel mới tuân theo kiểu triển khai AndroidView của Compose và ngừng sử dụng ViewBased SpatialPanel trước đó.
• Thêm đối tượng đồng hành VolumeConstraints.Unbounded đại diện cho các quy tắc ràng buộc không ràng buộc.
• Thêm SubspaceModifier.onPointSourceParams để cho phép nguồn âm thanh không gian.
• Thêm ApplicationSubspace công khai, cung cấp VolumeConstraints không bắt buộc để xác định vùng 3D mà ứng dụng có thể hiển thị nội dung không gian. Theo mặc định, nếu không có quy tắc ràng buộc nào được chỉ định, thì Không gian con sẽ được giới hạn bởi trường nhìn hiện tại của SpatialUser theo chiều rộng và chiều cao. Người dùng có thể cung cấp các quy tắc ràng buộc để sử dụng nếu không xác định được trường nhìn. Nếu không, các giá trị chiều rộng và chiều cao của trường nhìn mặc định sẽ được sử dụng.
• Thêm SpatialExternalSurface có thể dùng để kết xuất nội dung 3D. Bạn có thể tuỳ chỉnh SpatialExternalSurface bằng các đối tượng sửa đổi (ngoại trừ alpha) và hiệu ứng làm mềm cạnh.
• Thêm Đối tượng sửa đổi không gian con pointerHoverIcon mới cho phép người dùng đặt biểu tượng cho con trỏ không gian.

Thay đổi về API

• Xoá hạn chế RequiresApi(34) trên tất cả gói Jetpack XR. Quy định hạn chế này là thừa vì Jetpack XR hiện chỉ có trên các thiết bị có API cấp 34 trở lên. (Iae0f8)
• Các dự án phát hành bằng Kotlin 2.0 yêu cầu sử dụng KGP 2.0.0 trở lên. (Idb6b5)
• Giờ đây, tính năng xử lý thao tác quay lại sẽ hoạt động trên các bảng không gian mà không cần các hoạt động được nhúng. Để tính năng xử lý thao tác quay lại hoạt động, bạn cần chỉ định android:enableOnBackInvokedCallback="true" trong tệp kê khai Android.
• Giờ đây, tính năng xử lý thao tác quay lại sẽ hoạt động trên hộp thoại không gian. Để tính năng xử lý lui hoạt động, bạn cần chỉ định android:enableOnBackInvokedCallback="true" trong tệp kê khai Android.
• Giờ đây, SpatialPanel dựa trên Compose và Khung hiển thị có thể tự định cỡ dựa trên nội dung của chúng.
• Giờ đây, nhà phát triển có thể đặt giá trị SpatialElevationLevel tuỳ chỉnh của riêng mình và không bị giới hạn ở các cấp được xác định trước.
• Giờ đây, bạn có thể tuỳ chỉnh độ cao của vệ tinh nhân tạo thông qua thông số elevation.
• Theo mặc định, không gian con có thể được giới hạn bởi trường nhìn của SpatialUser theo chiều rộng và chiều cao. Nếu không xác định được trường nhìn, thì các giá trị chiều rộng và chiều cao của trường nhìn mặc định sẽ được sử dụng.
• Thêm lệnh gọi lại mới onMoveStart và onMoveEnd vào đối tượng sửa đổi Movable. Lệnh gọi lại onMoveStart và onMoveEnd được gọi khi người dùng bắt đầu và kết thúc việc di chuyển một thành phần kết hợp không gian con bằng đối tượng sửa đổi có thể di chuyển.
• Tham số name đã bị xoá khỏi các API không gian như SpatialRow và SpatialPanel. Để gỡ lỗi cây Compose không gian, hãy sử dụng SubspaceModifier.testTag.
• Xoá phương thức nạp chồng không được hỗ trợ của SpatialPopup chỉ có spatialElevationLevel và content. Vui lòng sử dụng giao diện hỗ trợ onDimissRequest.
• Xoá lệnh gọi lại onPoseChange khỏi đối tượng sửa đổi Movable (Có thể di chuyển). Thay vào đó, hãy sử dụng onMove.
• SubspaceModifiers sẽ không còn áp dụng hiệu ứng nếu các hiệu ứng đó bị tách rời hoặc đang tách rời.
• API SpatialRow hiện có đã được chia thành SpatialRow và SpatialCurvedRow. Nếu trước đây bạn sử dụng tham số curveRadius của SpatialRow, thì giờ đây, hãy sử dụng SpatialCurvedRow để cung cấp hành vi tương tự.
• MainPanel và ActivityPanel không còn có thanh tiêu đề khi chạy trên một hình ảnh hệ thống gần đây tương tự.
• Các đối tượng sửa đổi độ đậm nhạt và tỷ lệ hiện có thể xếp chồng và sẽ nhân giá trị của các đối tượng đó cho giá trị độ đậm nhạt hoặc tỷ lệ được áp dụng cuối cùng.
• Lệnh gọi lại onPoseChange từ đối tượng sửa đổi Movable (Có thể di chuyển) đã được tối ưu hoá để thực hiện chuyển động tư thế mượt mà hơn.
• Các đối tượng sửa đổi có thể di chuyển và thay đổi kích thước hiện sẽ thực hiện lệnh gọi lại trên luồng chính để đảm bảo rằng các thay đổi về trạng thái sẽ kích hoạt quá trình kết hợp lại.
• Thêm tính năng quan sát trạng thái vào các giai đoạn bố cục và đo lường để đảm bảo rằng các thay đổi về trạng thái trong SubspaceLayout sẽ kích hoạt việc bố cục lại.
• Tối ưu hoá nội dung cập nhật chuỗi đối tượng sửa đổi để sử dụng lại các đối tượng sửa đổi hiện có hiệu quả hơn.

Sửa lỗi

• Ngừng quét khi SpatialDialog xuất hiện. (Ic4594)
• Giờ đây, các yêu cầu bố cục lại được thực hiện trong khi các nút đối tượng sửa đổi bị tách rời sẽ bị bỏ qua.
• Xoá các giai đoạn bố cục lại do đối tượng sửa đổi Movable (Có thể di chuyển) và Resizable (Có thể đổi kích thước) kích hoạt.
• Khắc phục sự cố trong thành phần kết hợp MainPanel() xảy ra khi một trong hai kích thước được đặt thành 0, trực tiếp hoặc trong quá trình tính toán bố cục, ví dụ: tính toán SpatialRow/SpatialColumn. Giờ đây, bảng điều khiển sẽ bị ẩn. Xin lưu ý rằng bản sửa lỗi này giải quyết cụ thể các sự cố trong giai đoạn bố cục; việc đổi kích thước bảng điều khiển về 0 thông qua hoạt động tương tác của người dùng sẽ được xử lý riêng. Bảng điều khiển ẩn thiếu các tính năng hỗ trợ giao diện người dùng.
• Khắc phục vấn đề với maintainAspectRatio từ đối tượng sửa đổi có thể đổi kích thước. Bây giờ, tỷ lệ khung hình sẽ được giữ nguyên.
• Khắc phục vấn đề về các Không gian con lồng nhau, trong đó các không gian này sẽ được định vị không chính xác cho một khung hình.
• Khắc phục vấn đề đôi khi các góc bo tròn không được áp dụng khi cần.
• NestedSubspaces sẽ không còn xuất hiện cho một khung hình ở sai vị trí nữa.

Phiên bản 1.0.0-alpha03

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

Phát hành androidx.xr.compose:compose:1.0.0-alpha03 và androidx.xr.compose:compose-testing:1.0.0-alpha03 mà không có thay đổi đáng kể nào kể từ bản phát hành alpha gần đây nhất. Phiên bản 1.0.0-alpha03 bao gồm các thay đổi sau

Phiên bản 1.0.0-alpha02

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

Phát hành androidx.xr.compose:compose:1.0.0-alpha02 và androidx.xr.compose:compose-testing:1.0.0-alpha02. Phiên bản 1.0.0-alpha02 bao gồm các thay đổi sau.

Tính năng mới

• Giờ đây, Bảng điều khiển hoạt động có thể thu nhỏ nội dung khi Hộp thoại không gian được kích hoạt.
• API Orbiter hiện có thể sử dụng trong ngữ cảnh SubspaceComposable và sẽ đính kèm Orbiter vào thành phần mẹ có khả năng kết hợp dựa trên SubspaceLayout gần nhất.
• Giới thiệu LayoutCoordinatesAwareModifierNode để cho phép các đối tượng sửa đổi dựa trên vị trí tuỳ chỉnh.
• Thêm các phương thức vòng đời đính kèm/nhả vào SubspaceModifier.Node.
• Thêm scaleWithDistance vào đối tượng sửa đổi có thể di chuyển. Khi scaleWithDistance được bật, phần tử không gian con đã di chuyển sẽ tăng hoặc giảm. Chế độ này cũng sẽ duy trì mọi tỷ lệ rõ ràng mà nó có trước khi di chuyển.

Thay đổi về API

• Xoá SessionCallbackProvider và thay bằng SpatialCapabilities.

Các thay đổi khác

• Giảm minSDK xuống còn 24. Tất cả API Jetpack XR vẫn yêu cầu API 34 trong thời gian chạy.
• Hàm khởi tạo Orbiter EdgeOffset.inner, EdgeOffset.outer và EdgeOffset.overlap không còn là phương thức @Composable, cho phép sử dụng các hàm này trong ngữ cảnh không có khả năng kết hợp.
• Cập nhật Cấp độ độ cao không gian để phù hợp với thông số kỹ thuật mới nhất về trải nghiệm người dùng.
• Triển khai giao diện SubspaceSemanticsInfo vào MeasurableLayout.
• Đổi tên SubspaceModifierElement thành SubspaceModifierNodeElement.

Sửa lỗi

• Sửa lỗi để ổn định thứ tự SubspaceModifier. SubspaceModifier sẽ hoạt động ổn định hơn. Giờ đây, bạn có thể sử dụng đối tượng sửa đổi độ lệch, xoay, tỷ lệ, có thể di chuyển và đổi kích thước theo thứ tự bất kỳ.

Phiên bản 1.0.0-alpha01

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

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

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

• Bản phát hành đầu tiên dành cho nhà phát triển của Jetpack Compose cho XR. Sử dụng các khái niệm quen thuộc trong Compose như hàng và cột để tạo bố cục giao diện người dùng không gian trong XR, cho dù bạn đang chuyển một ứng dụng 2D hiện có sang XR hay tạo một ứng dụng XR mới từ đầu. Thư viện này cung cấp các thành phần kết hợp không gian và không gian con: chẳng hạn như bảng điều khiển không gian và vệ tinh, cho phép bạn đặt giao diện người dùng 2D Compose hoặc Views hiện có trong bố cục không gian. Phiên bản này giới thiệu thành phần kết hợp không gian con Volume, cho phép bạn đặt các thực thể SceneCore (chẳng hạn như mô hình 3D) tương ứng với giao diện người dùng. Tìm hiểu thêm trong hướng dẫn dành cho nhà phát triển này:

  • Subspace: Bạn có thể đặt thành phần kết hợp này ở bất kỳ vị trí nào trong hệ phân cấp giao diện người dùng của ứng dụng, cho phép bạn duy trì bố cục cho giao diện người dùng 2D và không gian mà không làm mất ngữ cảnh giữa các tệp. Điều này giúp bạn dễ dàng chia sẻ những thứ như cấu trúc ứng dụng hiện có giữa XR và các hệ số hình dạng khác mà không cần chuyển trạng thái lên trên toàn bộ cây giao diện người dùng hoặc thiết kế lại ứng dụng.

  • SpatialPanel: Bảng điều khiển không gian là một thành phần kết hợp không gian con cho phép bạn hiển thị nội dung ứng dụng – ví dụ: bạn có thể hiển thị chế độ phát video, hình ảnh tĩnh hoặc bất kỳ nội dung nào khác trong bảng điều khiển không gian.

  • Vệ tinh nhân tạo: Vệ tinh nhân tạo là một thành phần giao diện người dùng không gian. Thành phần này được thiết kế để đính kèm vào một bảng điều khiển không gian tương ứng và chứa các mục thao tác điều hướng và theo ngữ cảnh liên quan đến bảng điều khiển không gian đó. Ví dụ: nếu đã tạo một bảng điều khiển không gian để hiển thị nội dung video, bạn có thể thêm các nút điều khiển phát video bên trong một vệ tinh nhân tạo.

  • Thể tích: Đặt các thực thể SceneCore, chẳng hạn như mô hình 3D, tương ứng với giao diện người dùng.

• Bố cục không gian: Bạn có thể tạo nhiều bảng điều khiển không gian và đặt các bảng điều khiển đó trong một Bố cục không gian bằng cách sử dụng SpatialRow, SpatialColumn, SpatialBox và SpatialLayoutSpacer. Sử dụng SubspaceModifier để tuỳ chỉnh bố cục.

• Thành phần giao diện người dùng không gian: Bạn có thể sử dụng lại các phần tử này trong giao diện người dùng 2D và các thuộc tính không gian của chúng sẽ chỉ hiển thị khi bạn bật các tính năng không gian.

  • SpatialDialog: Bảng điều khiển sẽ đẩy nhẹ về sau theo chiều sâu z để hiển thị hộp thoại nâng cao.
  • SpatialPopUp: Bảng điều khiển sẽ đẩy nhẹ về sau trong chiều sâu z để hiển thị một cửa sổ bật lên nâng cao
  • SpatialElevation: Bạn có thể đặt SpatialElevationLevel để thêm độ cao.

• SpatialCapabilities: Các chức năng không gian có thể thay đổi khi người dùng tương tác với ứng dụng hoặc hệ thống, hoặc thậm chí có thể do chính ứng dụng của bạn thay đổi, ví dụ: chuyển sang Không gian chính hoặc Không gian toàn màn hình. Để tránh các vấn đề, ứng dụng của bạn cần kiểm tra LocalSpatialCapabilities.current để xác định những API nào được hỗ trợ trong môi trường hiện tại. isSpatialUiEnabled: Các thành phần giao diện người dùng không gian (ví dụ: SpatialPanel) isContent3dEnabled: Các đối tượng 3D isAppEnvironmentEnabled: Môi trường isPassthroughControlEnabled: Liệu ứng dụng có thể kiểm soát trạng thái truyền qua hay không isSpatialAudioEnabled: Âm thanh không gian

Lỗi đã biết

• Hiện tại, bạn cần có minSDK 30 để sử dụng Jetpack Compose cho XR. Để khắc phục, bạn có thể thêm mục nhập tệp kê khai <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> sau đây để có thể tạo và chạy với minSDK là 23.
• Các ứng dụng Jetpack XR hiện yêu cầu bạn phải yêu cầu quyền android.permission.SCENE_UNDERSTANDING trong AndroidManifest.
• Khi một ứng dụng khởi chạy trực tiếp vào Toàn không gian bằng cách sử dụng thuộc tính PROPERTY_XR_ACTIVITY_START_MODE trong tệp kê khai, Hoạt động/Ứng dụng ban đầu sẽ được mở trong Không gian chính trước khi chuyển sang Toàn không gian.
• Ban đầu, glTF trong các thành phần kết hợp Volume có thể nhấp nháy ở vị trí không chính xác.
• Việc sử dụng SpatialDialog trong một bảng điều khiển đã được di chuyển đáng kể sẽ đẩy nội dung theo hướng không chính xác.