XrSpatialAnchor QML Type
在真实空间中追踪特定位置或物体。更多...
| Import Statement: | import QtQuick3D.Xr |
| Since: | Qt 6.8 |
| Inherits: | |
| Status: | Technology preview |
此类型目前处于技术预览阶段，可能会有变动。
属性
- Classification : enumeration
- classification : enumeration
- classificationString : string
- extent2D : vector2d
- extent3D : vector3d
- has2DBounds : bool
- has3DBounds : bool
- identifier : string
- offset2D : vector2d
- offset3D : vector3d
- position : vector3d
- rotation : quaternion
详细说明
此类表示一种空间锚点，用于追踪现实空间中的特定位置或物体。它提供有关锚点位置、旋转、分类和边界的信息。
可通过XrSpatialAnchorListModel 访问空间锚点。
注意：系统 提供 Anchor 对象，无法在 QML 中创建。
有关如何使用此类型的示例，请参阅“Qt Quick 3D - XR 空间锚点示例”。
平台说明
Meta Quest 设备
此 API 使用了 Meta Quest 场景和空间锚点 API。您需要在应用的AndroidManifest.xml 文件中添加以下权限：
<uses-permission android:name="com.oculus.permission.USE_ANCHOR_API"/>
<uses-permission android:name="com.oculus.permission.USE_SCENE"/>注意： 在运行应用之前，您 需要手动设置一个空间（Space），否则锚点将不可用。
属性文档
Classification : enumeration [read-only]
空间锚点的分类。
“分类”枚举提供了一组预定义的类别类型，用于描述空间锚点的用途或上下文。
| 常量 | 描述 |
|---|---|
Classification.Unknown | 标签尚未设置或识别。 |
Classification.Wall | 该锚点代表一堵墙。 |
Classification.Ceiling | 该锚点代表天花板。 |
Classification.Floor | 该锚点代表地板。 |
Classification.Table | 该锚点代表一张桌子。 |
Classification.Seat | 该锚点代表一个座位。 |
Classification.Window | 锚点代表一扇窗户。 |
Classification.Door | 该锚点代表一扇门。 |
Classification.Other | 该锚点未被识别为上述任何一种类型。参见：classificationString |
下表展示了Qt Quick 3D Xr、OpenXR和VisionOS中分类类型的映射关系。如果系统提供的分类类型不在已定义类型范围内，则“Type”字段将设置为Other ，系统类型由classificationString 属性提供。
注意： 分类字符串也可以是Other 。
| Type | OpenXR | VisionOS | 描述 |
|---|---|---|---|
| 未知 | - | - | 该标签尚未设置或识别。 |
| 墙 | WALL_FACE | 墙 | 该锚点代表一堵墙。 |
| 天花板 | 天花板 | 天花板 | 该锚点代表天花板。 |
| 地板 | 地板 | 地板 | 该锚点代表一个楼层。 |
| 表 | 表 | 表 | 该锚点代表一个桌子。 |
| 座椅 | 沙发 | 座位 | 该锚点代表一个座位。 |
| Window | WINDOW_FRAME | 窗户 | 该锚点代表一个窗口。 |
| 门 | DOOR_FRAME | 门 | 该锚点代表一扇门。 |
| 其他 | - | - | 该锚点代表其他内容。参见：classificationString |
classification : enumeration [read-only]
空间锚点的分类类型。
该属性返回该锚点的classification type （例如，Table 或Floor ），用于描述锚点的用途或上下文。
注意： 来自系统的分类类型可能不在Classification 枚举定义的标签集合中，在这种情况下，该类型将被设置为Other ，而classificationString 属性将包含原始标签。
另请参阅 classificationString 。
classificationString : string [read-only]
空间锚点的分类类型（字符串）。
如果存在分类类型，该属性将返回该分类类型的字符串表示形式。如果分类类型不在Classification 枚举定义的类型集合中，则标签将设置为Other ，此时可通过该属性访问系统报告的原始类型。
注意：该 字符串可能为空或发生变化，具体取决于系统以及锚点的分类方式。
另请参阅 classification 。
extent2D : vector2d [read-only]
空间锚点的二维范围。
该属性存储空间锚点在X/Z平面内的二维尺寸（宽度和高度）。当has2DBounds 为true 时，该属性有效。
另请参阅 has2DBounds 和offset2D 。
extent3D : vector3d [read-only]
空间锚点的三维范围。
该属性指定了空间锚点在三维空间（宽度、高度和深度）中的体积。当has3DBounds 为true 时，该属性有效。
另请参阅 offset3D 和has3DBounds 。
has2DBounds : bool [read-only]
指示空间锚点是否具有二维边界。
如果空间锚点具有由offset2D 和extent2D 描述的二维边界，则该属性返回true ，这表明它代表一个平面（例如地板或墙壁）。
否则，返回 false。
另请参阅 offset2D 、extent2D 和has3DBounds 。
has3DBounds : bool [read-only]
指示空间锚点是否具有 3D 边界。
如果空间锚点具有三维边界，则此属性返回true ，表示它代表一个体积（例如，一张桌子或一个壁橱）。边界由offset3D 和extent3D 描述。
否则，它返回 `false`。
另请参阅 offset3D 、extent3D 以及has2DBounds 。
identifier : string [read-only]
该空间锚点的唯一标识符。
该属性包含与该空间锚点相关联的唯一标识符。该标识符与XrSpatialAnchorListModel 中引用的标识符相同。
offset2D : vector2d [read-only]
空间锚点的 2D 偏移量。
该属性存储锚点边界在 X/Z 平面内的偏移量。当has2DBounds 为true 时，该属性有效。
另请参阅 has2DBounds 和extent2D 。
offset3D : vector3d [read-only]
空间锚点的 3D 偏移量。
该属性提供锚点边界相对于其position 的3D偏移量（单位为米）。
另请参阅 offset3D 和has3DBounds 。
position : vector3d [read-only]
空间锚点的位置。
该属性返回空间锚点原点在会话坐标系中的三维位置（单位为米）。
rotation : quaternion [read-only]
空间锚点的方向。
该属性返回空间锚点的旋转信息（以四元数形式表示）。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
