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 的簡寫,可讓測試架構在測試中找到元素。