了解子空间修饰符

适用的 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)。

移动元素

借助可移动的修饰键,用户可以抓取并重新定位子空间元素。

  • transformingMovable:将此修饰符用于标准移动。此修饰符用于将元素配置为可供用户互动和移动。系统会根据用户输入自动计算并应用新的姿势和缩放比例。

  • movable:使用此修饰符可定义自定义移动行为。 虽然系统会提供移动可供性,但您必须使用必需的 onMove 事件并应用结果。这对于限制移动或在应用中创建自定义移动非常有用。

调整元素大小

可调整大小的修饰符可让用户抓取并调整子空间元素的大小。

  • transformingResizable:使用此修饰符可实现系统管理的调整大小。此修饰符会自动处理调整大小手势,并应用用户指定的新尺寸。

  • resizable:使用此修饰符可实现自定义调整大小逻辑。虽然系统提供了调整大小的可供性 (affordance),但您必须使用 onResize 事件并应用结果。此修饰符适用于复杂场景,例如在调整大小结束后保持特定宽高比或重新调整其他组件的整体布局。

更改可组合项的外观

alpha

alpha 修饰符用于设置元素及其子元素的不透明度,其中 0f 表示完全透明,1.0f 表示完全不透明。

scale

scale 修饰符可沿水平轴、垂直轴和深度轴缩放可组合项的内容。

测试和无障碍功能

semantics

semantics 修饰符会向布局节点添加语义,以便用于测试和无障碍功能。请参阅 Jetpack Compose 中的语义SemanticsModifier

testTag

testTag 修饰符是 SemanticsPropertyReceiver.testTag 的简写形式,可让测试框架在测试中找到相应元素。