瞭解子空間修飾符

適用的 XR 裝置
本指南可協助您為這類 XR 裝置打造體驗。
XR 頭戴式裝置
有線 XR 眼鏡

SubspaceModifier 類似於 Subspace 中可組合項的 Compose 修飾符。SubspaceModifier 可讓您在 3D 空間中操控可組合項,協助您定位、旋轉 3D 版面配置節點,以及為節點新增行為。

版面配置

根據預設,Subspace 會受限於建議的應用程式檢視空間。測量子空間元件的版面配置時,會使用這些邊界,類似於 2D Compose 版面配置中的邊界。

填滿邊界

修飾符 fillMaxSize、fillMaxWidth、fillMaxHeight 和 fillMaxDepth 可讓內容 (部分) 填滿其父項的邊界。使用填滿修飾符,可讓應用程式版面配置內容不受 XR 裝置的顯示特性影響。

設定大小和必要大小

修飾符 size、width、height 和 depth 會宣告內容的首選大小。如要宣告內容的確切大小,請使用 requiredSize、requiredWidth、requiredHeight 和 requiredDepth。這些單位必須以 dp 指定;如要將公尺轉換為 dp,請使用 Meter.toDp()。

放置可組合項

offset

offset 修飾符會沿著 x、y 和 z 軸,在 3D 空間中移動可組合項。這些單位必須以 dp 指定;如要從公尺轉換為 dp,請使用 Meter.toDp()。

rotate

rotate 修飾符會旋轉空間中的指定可組合函式。您可以透過不同方式指定旋轉方向和角度:

  • 使用俯仰角、偏航角和滾轉角,分別指定繞 x、y 和 z 軸的旋轉角度。
  • 使用 axisAngle (代表旋轉軸的 Vector3) 和應旋轉的角度,
  • 使用代表旋轉角度的 Quaternion。

rotateToLookAtUser

rotateToLookAtUser 修飾符會持續旋轉內容,讓內容隨時面向使用者。您也可以使用這個修飾符達到「廣告看板」效果,讓內容在 Y 軸上旋轉面向使用者,同時保持直立並與重力對齊。如要這麼做,請將 rotateToLookAtUser 修飾符與 gravityAligned 修飾符結合。

移動可組合項及調整大小

讓使用者直接操控 3D 空間中物件的位置和大小。

移動元素

如果 movable 修飾符存在且已啟用,系統會顯示可拖曳的 UI 控制項,讓使用者在 3D 空間中移動元素。您可以將 movable 修飾符套用至整個 Subspace、空間版面配置元件 (例如 SpatialRow 和 SpatialColumn),以及個別元件 (例如 SpatialPanel 和 SpatialGltfModel)。

這項移動的具體行為是由提供的 movePolicy 定義:

  • MovePolicy.Default (或 MovePolicy.system()):系統會完全處理移動作業,並根據使用者輸入內容,自動計算及套用新的姿勢和比例。
  • MovePolicy.custom():系統會根據輸入內容計算目標 Pose,但不會自動套用至相關聯的元素。這項功能可用於限制移動,或在應用程式中建立自訂移動。
  • MovePolicy.anchor():可讓使用者將可移動元素貼齊並錨定至偵測到的真實世界平面。

錨定可組合項

如要將可移動的子空間可組合項錨定至現實世界的表面,請將 MovePolicy.anchor() 傳遞至 movable 修飾符。這項政策可讓使用者將元素 (例如 SpatialPanel 和 SpatialGltfModel) 貼齊桌子、牆壁或地板等實體表面。

您可以使用下列參數,篩選元素可貼齊的偵測平面 (如果留空,元素可以錨定到任何偵測到的平面):

  • anchorPlaneOrientations:一組 PlaneOrientation 值 (Horizontal、Vertical 或 Any)。
  • anchorPlaneSemantics:一組 PlaneSemantic 值 (Wall、Floor、Ceiling、Table 或 Any)。

調整元素大小

如果 resizable() 修飾符存在且已啟用,系統會顯示 UI 控制項,讓使用者在 3D 空間中調整元素大小。調整大小的具體行為由提供的 resizePolicy 定義:

  • ResizePolicy.default():系統會自動處理調整大小手勢,並將新尺寸套用至內容。
  • ResizePolicy.custom():系統會提供 SpatialResizeEvent,但不會自動將調整大小的結果套用至相關聯的元素。

變更可組合項的外觀

alpha

alpha 修飾符可設定元素及其子項的不透明度,其中 0f 代表完全透明,1.0f 代表完全不透明。

scale

scale 修飾符會沿著水平、垂直和深度軸縮放可組合項的內容。

測試和無障礙功能

semantics

semantics 修飾符會為版面配置節點新增語意,用於測試和無障礙功能。請參閱「Jetpack Compose 中的語意」和 SemanticsModifier。

testTag

testTag 修飾符是 SemanticsPropertyReceiver.testTag 的簡寫,可讓測試架構在測試中找到元素。