瞭解子空間修飾符

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

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

版面配置

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

填滿界線

修飾符 fillMaxSizefillMaxWidthfillMaxHeightfillMaxDepth 可讓內容 (部分) 填滿父項的界線。使用填滿修飾符可協助應用程式版面配置與 XR 裝置螢幕特性無關的內容。

設定大小和必要大小

修飾符 sizewidthheightdepth 會宣告內容的偏好大小。如要宣告內容的確切大小,請使用 requiredSizerequiredWidthrequiredHeightrequiredDepth。這些單位必須以 dp 指定;如要從公尺轉換為 dp,請使用 Meter.toDp()

定位可組合函式

offset

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

rotate

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

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

rotateToLookAtUser

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

使用可組合函式移動及調整大小

讓使用者直接操控 3D 空間中物體的位置和大小。您可以將這些修飾符新增至個別元件 (例如 SpatialPanel)、子空間和空間版面配置元件 (例如 SpatialRowSpatialColumn)。

移動元素

使用者可以抓取並重新放置子空間元素。

  • transformingMovable:使用這個修飾符進行標準移動。這項修飾符會將元素設為可供使用者互動和移動。系統會根據使用者輸入內容,自動計算並套用新的姿勢和比例。

  • movable:使用這個修飾符定義自訂移動行為。系統會提供移動功能,但您必須使用必要的 onMove 事件並套用結果。這項功能可限制移動,或在應用程式中建立自訂移動。

調整元素大小

使用者可以透過可調整大小的修飾符,抓取並調整子空間元素的大小。

  • transformingResizable:使用這個修飾符進行系統管理的大小調整作業。這個修飾符會自動處理大小調整手勢,並套用使用者指定的新尺寸。

  • resizable:使用這個修飾符可自訂大小調整邏輯。系統會提供大小調整功能,但您必須使用 onResize 事件並套用結果。這項修飾符適用於複雜情境,例如維持特定顯示比例,或在調整大小結束後重新調整其他元件的整體版面配置。

變更可組合函式外觀

alpha

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

scale

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

測試和無障礙功能

semantics

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

testTag

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