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 修饰符可使可组合项在 3D 空间中沿 x、y 和 z 轴移动。这些单位必须以 dp 指定;如需将米转换为 dp,请使用 Meter.toDp()。
rotate
rotate 修饰符可使指定可组合项在空间中旋转。您可以通过多种方式指定旋转方向和角度:
- 使用俯仰角、偏航角和横滚角,分别对应围绕
x、y和z轴的旋转, - 使用
axisAngle,即通过一个Vector3表示旋转轴,并指定围绕该轴的旋转角度(以度为单位), - 使用
Quaternion表示旋转。
rotateToLookAtUser
修饰符 rotateToLookAtUser 会持续旋转
内容,使其始终面向用户。您还可以使用此修饰符实现“广告牌”效果,即内容会围绕
Y 轴旋转以面向用户,同时仍保持直立并与重力对齐。为此,
请将 rotateToLookAtUser 修饰符与
gravityAligned 修饰符结合使用。
使用可组合项移动和调整大小
让用户直接操纵 3D 空间中对象的位置和大小。您可以将这些修饰符添加到各个组件(如 SpatialPanel)、子空间和空间布局组件(如
SpatialRow 或 SpatialColumn)。
移动元素
当 movable 修饰符存在且处于启用状态时,系统会显示可拖动的界面
控件,让用户可以在 3D 空间中移动元素。此移动的具体行为由提供的
movePolicy 定义:
MovePolicy.default:系统会完全处理移动,并根据用户输入自动计算和应用新的姿势和缩放比例。MovePolicy.custom:系统会根据输入计算目标姿势,但不会自动将其应用于关联的元素。这对于限制移动或在应用中创建自定义移动非常有用。
调整元素大小
当 resizable() 修饰符存在且处于启用状态时,系统会显示界面控件
,让用户可以在 3D 空间中调整元素大小。调整大小的具体行为由提供的
resizePolicy 定义:
ResizePolicy.default():系统会自动处理调整大小的手势,并将新尺寸应用于内容。ResizePolicy.custom():系统会提供SpatialResizeEvent,但不会自动将调整大小的结果应用于关联的元素。
更改可组合项的外观
alpha
alpha 修饰符用于设置元素及其子元素的不透明度,其中 0f 表示完全透明,1.0f 表示完全不透明。
scale
修饰符 scale 会沿
水平轴、垂直轴和深度轴缩放可组合项的内容。
测试和无障碍功能
semantics
修饰符 semantics 会向布局节点添加语义,以便用于
测试和无障碍功能。请参阅 Jetpack Compose 中的语义和
SemanticsModifier。
testTag
修饰符 testTag 是
SemanticsPropertyReceiver.testTag 的简写形式,可让测试框架在测试中查找
元素。