Tìm hiểu về đối tượng sửa đổi không gian con

Các thiết bị XR được hỗ trợ
Hướng dẫn này giúp bạn xây dựng các trải nghiệm cho những loại thiết bị XR sau.
Tìm hiểu về các loại thiết bị XR →
Thiết bị đeo đầu XR
Kính thông minh XR có dây
Tìm hiểu về các loại thiết bị XR →

SubspaceModifier tương tự như đối tượng sửa đổi Compose cho các thành phần kết hợp trong Subspace. SubspaceModifier cho phép bạn thao tác với các thành phần kết hợp trong không gian 3D, giúp bạn định vị, xoay và thêm hành vi vào các nút bố cục 3D.

Bố cục

Theo mặc định, Subspace được giới hạn trong không gian đề xuất để xem một ứng dụng. Các giới hạn này được dùng khi đo lường bố cục của các thành phần không gian phụ, tương tự như giới hạn trong bố cục Compose 2D.

Lấp đầy ranh giới

Đối tượng sửa đổi fillMaxSize, fillMaxWidth, fillMaxHeight và fillMaxDepth làm cho nội dung lấp đầy (một phần) các giới hạn của thành phần mẹ. Việc sử dụng đối tượng sửa đổi lấp đầy giúp ứng dụng của bạn bố trí nội dung độc lập với các đặc điểm hiển thị của thiết bị XR.

Đặt kích thước và kích thước bắt buộc

Các đối tượng sửa đổi size, width, height và depth khai báo kích thước ưu tiên của nội dung. Để khai báo kích thước chính xác của nội dung, hãy sử dụng requiredSize, requiredWidth, requiredHeight và requiredDepth. Bạn phải chỉ định các đơn vị này bằng dp; để chuyển đổi từ mét sang dp, hãy sử dụng Meter.toDp().

Đặt vị trí cho các thành phần kết hợp

offset

Đối tượng sửa đổi offset di chuyển thành phần kết hợp trong không gian 3D dọc theo các trục x, y và z. Bạn phải chỉ định các đơn vị này bằng dp; để chuyển đổi từ mét sang dp, hãy sử dụng Meter.toDp().

rotate

Đối tượng sửa đổi rotate xoay thành phần kết hợp đã cho trong không gian. Bạn có thể chỉ định hướng và mức độ xoay theo nhiều cách:

  • Sử dụng độ cao, độ lệch và độ lăn, chỉ định chế độ xoay quanh các trục x, y và z tương ứng,
  • Sử dụng axisAngle (là Vector3 biểu thị trục xoay) và số độ cần xoay quanh trục,
  • Sử dụng Quaternion đại diện cho chế độ xoay.

rotateToLookAtUser

Đối tượng sửa đổi rotateToLookAtUser liên tục xoay nội dung để nội dung luôn hướng về phía người dùng. Bạn cũng có thể sử dụng đối tượng sửa đổi này để đạt được hiệu ứng "bảng quảng cáo", trong đó nội dung xoay để hướng về phía người dùng trên trục Y trong khi vẫn giữ nguyên vị trí thẳng đứng và căn chỉnh theo trọng lực. Để thực hiện việc này, hãy kết hợp đối tượng sửa đổi rotateToLookAtUser với đối tượng sửa đổi gravityAligned.

Di chuyển và đổi kích thước thành phần kết hợp

Cho phép người dùng trực tiếp điều chỉnh vị trí và kích thước của đối tượng trong không gian 3D.

Di chuyển phần tử

Khi đối tượng sửa đổi movable xuất hiện và được bật, các thành phần điều khiển trên giao diện người dùng có thể kéo được sẽ xuất hiện để người dùng di chuyển phần tử trong không gian 3D. Bạn có thể áp dụng đối tượng sửa đổi movable cho toàn bộ Subspace, các thành phần bố cục không gian (như SpatialRow và SpatialColumn) và các thành phần riêng lẻ (như SpatialPanel và SpatialGltfModel).

Hành vi cụ thể của chuyển động này được xác định bằng movePolicy được cung cấp:

  • MovePolicy.Default (hoặc MovePolicy.system()): Hệ thống xử lý hoàn toàn chuyển động, đồng thời tự động tính toán và áp dụng tư thế cũng như tỷ lệ mới dựa trên hoạt động đầu vào của người dùng.
  • MovePolicy.custom(): Hệ thống tính toán Pose mục tiêu dựa trên dữ liệu đầu vào, nhưng không tự động áp dụng cho phần tử liên kết. Điều này rất hữu ích để hạn chế chuyển động hoặc tạo chuyển động tuỳ chỉnh trong ứng dụng.
  • MovePolicy.anchor(): Cho phép người dùng chụp và neo phần tử có thể di chuyển vào các mặt phẳng thực tế được phát hiện.

Thành phần kết hợp neo

Để có thể neo một composable không gian phụ có thể di chuyển vào các bề mặt trong thế giới thực, hãy truyền MovePolicy.anchor() đến modifier movable. Chính sách này cho phép người dùng gắn các phần tử (chẳng hạn như SpatialPanel và SpatialGltfModel) vào các bề mặt thực tế như bàn, tường hoặc sàn.

Bạn có thể lọc các mặt phẳng được phát hiện mà một phần tử có thể bám vào bằng cách sử dụng các tham số sau (nếu để trống, phần tử có thể neo vào bất kỳ mặt phẳng nào được phát hiện):

  • anchorPlaneOrientations: Một tập hợp các giá trị PlaneOrientation (Horizontal, Vertical hoặc Any).
  • anchorPlaneSemantics: Một tập hợp các giá trị PlaneSemantic (Wall, Floor, Ceiling, Table hoặc Any).

Đổi kích thước phần tử

Khi đối tượng sửa đổi resizable() xuất hiện và được bật, các thành phần điều khiển trên giao diện người dùng sẽ xuất hiện để cho phép người dùng đổi kích thước phần tử trong không gian 3D. Hành vi cụ thể của thao tác đổi kích thước được xác định bằng resizePolicy được cung cấp:

  • ResizePolicy.default(): Hệ thống tự động xử lý cử chỉ đổi kích thước và áp dụng kích thước mới cho nội dung.
  • ResizePolicy.custom(): Hệ thống cung cấp một SpatialResizeEvent và không tự động áp dụng kết quả của việc đổi kích thước cho phần tử liên kết.

Thay đổi giao diện của thành phần kết hợp

alpha

Đối tượng sửa đổi alpha đặt độ mờ của phần tử và các phần tử con của phần tử đó, trong đó 0f đại diện cho độ trong suốt hoàn toàn và 1.0f đại diện cho độ mờ hoàn toàn.

scale

Đối tượng sửa đổi scale điều chỉnh tỷ lệ nội dung của thành phần kết hợp dọc theo trục ngang, trục dọc và trục chiều sâu.

Kiểm thử và hỗ trợ tiếp cận

semantics

Đối tượng sửa đổi semantics thêm ngữ nghĩa vào nút bố cục để dùng trong kiểm thử và hỗ trợ tiếp cận. Xem phần Ngữ nghĩa trong Jetpack Compose và SemanticsModifier.

testTag

Đối tượng sửa đổi testTag là viết tắt của SemanticsPropertyReceiver.testTag, cho phép các khung kiểm thử tìm thấy phần tử trong các kiểm thử.