了解子空间修饰符

适用的 XR 设备
本指南可帮助您为以下类型的 XR 设备打造优质体验。
扩展现实头戴设备
有线扩展现实眼镜

SubspaceModifier 类似于 Subspace 中可组合项 的 Compose 修饰符。借助 SubspaceModifier,您可以在 3D 空间中操纵可组合项,从而帮助您定位、旋转 3D 布局节点并为其添加行为。

布局

默认情况下,Subspace 的边界为应用推荐的可视空间范围。在测量子空间组件的布局时,系统会使用这些边界,这与 2D Compose 布局中的边界类似。

填充边界

修饰符 fillMaxSizefillMaxWidthfillMaxHeightfillMaxDepth 可使内容(部分)填充其父元素的边界。 使用填充修饰符有助于应用布局不受 XR 设备显示特性影响的内容。

设置尺寸和所需尺寸

修饰符 sizewidthheightdepth 用于声明内容的首选尺寸。如需声明内容的精确尺寸,请使用 requiredSizerequiredWidthrequiredHeightrequiredDepth。这些尺寸单位必须以 dp 指定;如需将米转换为 dp,请使用 Meter.toDp()

定位可组合项

offset

offset 修饰符可使可组合项在 3D 空间中沿 xyz 轴移动。这些单位必须以 dp 指定;如需将米转换为 dp,请使用 Meter.toDp()

rotate

rotate 修饰符可使指定可组合项在空间中旋转。您可以通过多种方式指定旋转方向和角度:

  • 使用俯仰角、偏航角和横滚角,分别对应围绕 xyz 轴的旋转,
  • 使用 axisAngle,即通过一个 Vector3 表示旋转轴,并指定围绕该轴的旋转角度(以度为单位),
  • 使用 Quaternion 表示旋转。

rotateToLookAtUser

修饰符 rotateToLookAtUser 会持续旋转 内容,使其始终面向用户。您还可以使用此修饰符实现“广告牌”效果,即内容会围绕 Y 轴旋转以面向用户,同时仍保持直立并与重力对齐。为此, 请将 rotateToLookAtUser 修饰符与 gravityAligned 修饰符结合使用。

使用可组合项移动和调整大小

让用户直接操纵 3D 空间中对象的位置和大小。您可以将这些修饰符添加到各个组件(如 SpatialPanel)、子空间和空间布局组件(如 SpatialRowSpatialColumn)。

移动元素

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

修饰符 testTagSemanticsPropertyReceiver.testTag 的简写形式,可让测试框架在测试中查找 元素。