Jetpack Compose cho XR

Xây dựng bố cục giao diện người dùng không gian một cách khai báo để tận dụng các chức 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 30 tháng 7 năm 2025 - - - 1.0.0-alpha05

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

Để thêm một phần phụ thuộc vào 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:

Groovy

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

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

Kotlin

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

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

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

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

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

Tính năng mới

  • Đã đặt lớp chú giải SubspaceComposable ở chế độ công khai. (Ic2a34, b/399432430)
  • Hai thành phần kết hợp SpatialExternalSurface mới biểu thị các hình cầu 180 và 360 độ. (I40ef2, b/391705799)
  • Thêm SubspaceModifier.aspectRatio (Ide5ab, b/399729509, b/414762147)
  • Đã thêm API SceneCoreEntity để cải thiện khả năng tương tác giữa SceneCore và Compose cho XR. (I50bb3, b/423020989)
  • Cung cấp API GravityAlignedsubspace để hỗ trợ tính năng GravityAligned chưa được điều chỉnh tỷ lệ (I07359)

Thay đổi về API

  • SpatialDialog() sẽ tuân theo cấu hình nhấn SpatialDialogProperties.dismissOnBack. (Ib453b, b/416797132)
  • Cập nhật minimumPanelDimension thành kích thước Phương diện mặc định mới là Dimensions(0.1f, 0.1f, 0.1f) do kích thước này được biểu thị bằng Mét. (Ib852a)
  • Giờ đây, các không gian con và Orbiter sẽ giữ lại trạng thái nội bộ của chúng trong không gian chính và khi ứng dụng ở chế độ nền. Ở chế độ không gian chính, Subspace vẫn sẽ thiết lập cảnh để chuẩn bị chuyển sang chế độ toàn không gian. (I40317, b/416037751)
  • SpatialDialogs nay sẽ giữ lại trạng thái của chúng khi ứng dụng ở chế độ nền. (I6aa56)
  • Giờ đây, ApplicationSubspace sẽ kế thừa tỷ lệ và vị trí được đề xuất từ hệ thống. (I4565f, b/418834194)
  • Thêm thông báo lỗi hiệu quả hơn và kích hoạt lỗi sớm hơn khi SubspaceComposable được dùng trong một ngữ cảnh không phải SubspaceComposable. (Iee2ae, b/416484684)
  • Cập nhật ExperimentalSubspaceVolumeApi từ Cảnh báo thành Lỗi vì cảnh báo thường bị bỏ qua khi sử dụng sai các API có thể kết hợp. (I427aa, b/424864286)
  • Không gian con và ApplicationSubspace hiện bị hạn chế bởi recommendedContentBoxInFullSpace. Trước đây, nó bị hạn chế bởi Trường nhìn của SpatialUser. (I41015, b/423074142)
  • Cập nhật SpatialElevation để sử dụng kích thước tối thiểu thay vì kích thước được mã hoá cứng (I2dbe6, b/427785338)
  • Cập nhật cách chúng ta che SpatialAcitivityPanel để cập nhật khi một biến khoá được sửa đổi. (I0f64d, b/427999029)
  • Xoá VolumeConstraints.Unbounded để đặt các giá trị ràng buộc mặc định thành giá trị tương đương. (Ie24ec, b/407938414)
  • SpatialFeatheringSize không còn ở chế độ công khai nữa (I1c15b, b/399432430)
  • Đổi tên Placeable XR thành SubspacePlaceable để phân biệt với Placeable của Compose. (I74874)
  • Xoá chế độ cài đặt Orbiter và thêm shouldRenderInNonSpatial làm tham số mới. Ngoài ra, hãy xoá lớp EdgeOffset và thêm orbiterOffsetType làm tham số mới để hợp nhất các hàm Orbiter(). Cũng như đổi tên OrbiterEdge thành ContentEdge. (Iebf3d)
  • Đổi tên Measurable thành SubspaceMeasurable để phân biệt loại này với loại Measurable của Compose. (I9726c)
  • Đổi tên MeasureResult thành SubspaceMeasureResult (I9f34d)
  • Xoá API setSubspaceContent để sử dụng setContent của Compose với thành phần kết hợp Subspace. (Ifff4c, b/421427391, b/421427391)
  • MeasurePolicy đổi tên thành SubspaceMeasurePolicy. (I37a9b, b/422553904)
  • Chuyển SubspaceSemanticsInfo thành một giao diện kín vì chúng ta sẽ không thể thêm các thành phần mà không có giá trị mặc định. (I372f9, b/423704068)
  • Cập nhật tài liệu SpatialExternalSurface, đổi tên ContentSecurityLevel thành SurfaceProtection (I3c460, b/420982808)
  • Cung cấp hàm khởi tạo quá tải cho đối tượng sửa đổi có thể di chuyển cho phép neo. (Ic0c70)
  • Thêm nhiều trình cung cấp vị trí hơn cho chú thích để giờ đây, nhà phát triển có thể kiểm soát việc chú thích được đặt ở phía trên, phía dưới, bên trái hay bên phải của điểm neo. Thêm một API nhận Shape cho dấu nháy, nhờ đó, bạn có thể cung cấp thêm nhiều hình dạng tuỳ chỉnh. (Ie513c, b/374766087, b/418854637)
  • Xoá CoreEntity khỏi PublishedApi (Ifee05)

Sửa lỗi

  • Khắc phục vấn đề SpatialDialog nhấp nháy khi được kết xuất. (Ife73c, b/401619909)
  • Khắc phục vấn đề SpatialDialog không thể che Bảng điều khiển hoạt động. (I8ca6c, b/367442109)
  • Khắc phục lỗi hộp thoại XR không hiển thị một số nội dung (I17cd5, b/418062437)
  • Khắc phục vấn đề SpatialPopup bị loại bỏ khi nhấp vào bên trong nội dung. (If262c, b/417245722)
  • Khắc phục vấn đề khi chuỗi resizable().movable(), SpatialPanel không thể đổi kích thước chính xác thành kích thước mới. (I02ee3, b/422264230)
  • Khắc phục lỗi topBar chồng lên trình đơn trong SpatialComposeVideoPlayer (Id33bc, b/427168167)
  • Khắc phục lỗi bán kính góc không hiển thị (I975fe, b/428261830)

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.

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à không dùng ViewBased SpatialPanel trước đó nữa.
  • Đã thêm đối tượng đồng hành VolumeConstraints.Unbounded, đại diện cho các ràng buộc không giới hạn.
  • Thêm SubspaceModifier.onPointSourceParams để cho phép nguồn âm thanh được không gian hoá.
  • Một ApplicationSubspace công khai đã được thêm, cung cấp VolumeConstraints không bắt buộc để xác định một vùng 3D nơi ứng dụng có thể hiển thị nội dung không gian. Theo mặc định, nếu không có điều kiện ràng buộc nào được chỉ định, Subspace sẽ bị 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 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 mặc định của trường nhìn sẽ được sử dụng.
  • Đã thêm SpatialExternalSurface, có thể dùng để kết xuất nội dung lập thể. SpatialExternalSurface có thể tuỳ chỉnh bằng các đối tượng sửa đổi (ngoại trừ alpha) và hiệu ứng làm mờ cạnh.
  • Thêm một Đối tượng sửa đổi không gian phụ 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) đối với tất cả các gói Jetpack XR. Hạn chế này là không cần thiết 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 đượ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)
  • Giờ đây, thao tác xử lý nút quay lại sẽ hoạt động trên các bảng điều khiển không gian mà không 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.
  • Tính năng xử lý thao tác quay lại hiện sẽ hoạt động trên các hộp thoại không gian. Để 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, các SpatialPanel dựa trên Compose và dựa trên Khung hiển thị có thể tự điều chỉnh kích thước dựa trên nội dung của chúng.
  • Giờ đây, nhà phát triển có thể đặt các 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 cấp độ độ cao của vệ tinh nhân tạo thông qua tham số elevation.
  • Giờ đây, không gian con có thể được giới hạn theo trường nhìn của SpatialUser về chiều rộng và chiều cao theo mặc định. 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 mặc định của trường nhìn sẽ được dùng.
  • Đã thêm các lệnh gọi lại onMoveStart và onMoveEnd mới vào đối tượng sửa đổi Movable. Các 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 thành phần không gian, hãy sử dụng SubspaceModifier.testTag.
  • Xoá một 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.
  • Lệnh gọi lại onPoseChange từ đối tượng sửa đổi Movable đã bị xoá. Thay vào đó, hãy sử dụng onMove.
  • SubspaceModifiers sẽ không còn áp dụng hiệu ứng nếu 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 để có hành vi tương tự.
  • MainPanel và ActivityPanel không còn thanh tiêu đề khi chạy trên một hình ảnh hệ thống tương tự gần đây.
  • Giờ đây, các đối tượng sửa đổi độ trong suốt và tỷ lệ có thể xếp chồng và sẽ nhân các giá trị của chúng cho giá trị độ trong suố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 tối ưu hoá để thực hiện chuyển động tư thế mượt mà hơn.
  • Giờ đây, các đối tượng sửa đổi có thể di chuyển và đổi kích thước sẽ thực hiện các 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 tái cấu trúc.
  • Thêm hoạt độ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 trạng thái trong SubspaceLayout sẽ kích hoạt quá trình bố trí lại.
  • Cập nhật chuỗi công cụ sửa đổi được tối ưu hoá để sử dụng lại các công cụ sửa đổi hiện có một cách hiệu quả hơn.

Sửa lỗi

  • Ngừng làm mờ khi SpatialDialog xuất hiện. (Ic4594)
  • Các yêu cầu bố trí lại được thực hiện trong khi các nút sửa đổi bị tách rời sẽ bị bỏ qua.
  • Xoá các giai đoạn bố trí lại do đối tượng sửa đổi Movable và Resizable 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 phương diện đượ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 đặc biệt giải quyết các sự cố trong giai đoạn bố cục; việc đổi kích thước bảng điều khiển thành 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 thành phần tương tác trên 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. Tỷ lệ khung hình hiện tại sẽ được giữ nguyên.
  • Khắc phục vấn đề với các Không gian con lồng nhau, trong đó các Không gian con này sẽ được đặt không đúng vị trí 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 đáng lẽ phải được áp dụng.
  • NestedSubspaces sẽ không còn xuất hiện trong 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

androidx.xr.compose:compose:1.0.0-alpha03 và androidx.xr.compose:compose-testing:1.0.0-alpha03 được phát hành 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ể làm mờ nội dung khi một hộp thoại không gian được kích hoạt.
  • Giờ đây, bạn có thể sử dụng API Orbiter trong các ngữ cảnh SubspaceComposable và sẽ đính kèm các Orbiter vào thành phần 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 chỉnh sửa tuỳ chỉnh dựa trên vị trí.
  • Thêm các phương thức trong vòng đời đính kèm/tách rời 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 được di chuyển sẽ tăng hoặc giảm kích thước. Nó 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ả các API Jetpack XR đều tiếp tục yêu cầu API 34 trong thời gian chạy.
  • Các hàm khởi tạo Orbiter EdgeOffset.inner, EdgeOffset.outer và EdgeOffset.overlap không còn là các phương thức @Composable nữa, cho phép sử dụng chúng trong các ngữ cảnh không kết hợp.
  • Cập nhật các cấp độ độ cao không gian cho phù hợp với quy cách trải nghiệm người dùng mới nhất.
  • 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 việc đặt hàng 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 dịch chuyển, xoay, thu phóng, di chuyển và đổi kích thước theo bất kỳ thứ tự nào.

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 của Jetpack Compose cho XR dành cho nhà phát triển. Sử dụng các khái niệm quen thuộc của 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ư các bảng không gian và các thành phần kết hợp quỹ đạo, cho phép bạn đặt giao diện người dùng 2D dựa trên Compose hoặc Views hiện có vào một bố cục không gian. Thành phần kết hợp này giới thiệu 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à giao diện người dùng không gian mà không làm mất bối 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 kiểu dáng thiết bị khác mà không cần phải nâng trạng thái thông qua toàn bộ cây giao diện người dùng hoặc thiết kế lại ứng dụng.

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

    • Orbiter: Orbiter là một thành phần giao diện người dùng không gian. Thanh này được thiết kế để gắn vào một bảng điều khiển không gian tương ứng, đồng thời chứa các mục hành động theo ngữ cảnh và điều hướng 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 vào bên trong một orbiter.

    • Âm lượng: Đặ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 chúng trong Bố cục không gian bằng cách dùng SpatialRow, SpatialColumn, SpatialBox và SpatialLayoutSpacer. Sử dụng SubspaceModifier để tuỳ chỉnh bố cục.

  • Các thành phần giao diện người dùng không gian: Bạn có thể 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ỉ xuất hiện khi bạn bật các chức năng không gian.

    • SpatialDialog: Bảng điều khiển sẽ đẩy nhẹ về phía sau theo chiều sâu z để hiển thị một hộp thoại nổi.
    • SpatialPopUp: Bảng điều khiển sẽ đẩy nhẹ về phía sau theo chiều sâu z để hiển thị một cửa sổ bật lên ở vị trí 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 của bạn, 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 Toàn không gian. Để tránh gặp phải vấn đề, ứng dụng của bạn cần kiểm tra LocalSpatialCapabilities.current để xác định những API được hỗ trợ trong môi trường hiện tại. isSpatialUiEnabled: Các phần tử giao diện người dùng không gian (ví dụ: SpatialPanel) isContent3dEnabled: Đối tượng 3D isAppEnvironmentEnabled: Môi trường isPassthroughControlEnabled: Ứ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 phải có minSDK là 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 cấp quyền android.permission.SCENE_UNDERSTANDING trong AndroidManifest.
  • Khi một ứng dụng khởi chạy trực tiếp vào chế độ 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, các Hoạt động/Ứng dụng ban đầu sẽ mở ở chế độ Không gian chính trước khi chuyển sang chế độ Toàn không gian.
  • glTF trong Volume Composables có thể nhấp nháy ở vị trí không chính xác vào lúc ban đầu.
  • 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 đi sai hướng.