Back to Qt.io
Contact Us Blog Download Qt

Node QML Type

三维场景中物体的基本组件。更多

Import Statement: import QtQuick3D
Inherits:

Object3D

Inherited By:
20 types

Affector3D, AxisHelper, Camera, Joint, Light, Loader3D, LodManager, LookAtNode, Model, ParticleEmitter3D, ParticleSystem3D, ReflectionProbe, Repeater3D, RuntimeLoader, Skeleton, XrCamera, XrController, XrItem, XrOrigin, and XrView

属性

方法

详细说明

节点类型是其他空间类型的基类，如Model,Camera,Light 。这些对象代表三维场景中存在的实体，在三维世界中具有位置和其他属性。除根节点外，所有节点类型都是相对于其父节点（即本地坐标）进行转换的。在许多方面，Node 类型在Qt Quick 3D 场景中的作用与Item 在Qt Quick 场景中的作用相同。

除了从 Node 派生的类型外，还可以将其他类型作为 Node 的父节点。这包括QObject 实例，其中 Node 仅作为QObject parent 和Qt Quick 项。

封装其他对象以便将其分组为组件或子树是一种方便的方法，例如，将一组节点作为一个整体动画化。本代码段展示了如何使用 Node 为摄像机制作动画：

Node {
    PerspectiveCamera {
        position: Qt.vector3d(0, 0, -600)
    }

    SequentialAnimation on eulerRotation.y {
        loops: Animation.Infinite
        PropertyAnimation {
            duration: 5000
            from: 0
            to: 360
        }
    }
}

如果在View3D 以外创建场景，例如为了即时切换场景或在多个视图上显示同一场景，也必须使用 Node。

Node {
    id: standAloneScene

    DirectionalLight {}

    Model {
        source: "#Sphere"
        materials: [ DefaultMaterial {} ]
    }

    PerspectiveCamera {
        z: 600
    }
}

View3D {
    importScene: standAloneScene
}

属性文档

eulerRotation : vector3d

该属性包含 x、y 和 z 轴的旋转值。这些值以向量 3d 的形式存储。旋转顺序假定为 ZXY。

另请参阅 QQuaternion::fromEulerAngles().


forward : vector3d [read-only]

该属性返回节点在场景空间中前进方向的归一化矢量。

另请参阅 up,right, 和mapDirectionToScene 。


opacity : real

该属性包含节点的局部不透明度值。由于节点对象不一定可见，因此该值可能不会产生任何影响，但该值会被节点的所有子节点继承，而这些子节点可能是可见的。


pivot : vector3d

该属性包含 x、y 和 z 轴的枢轴值。在对节点进行旋转时，这些值将用作支点。


position : vector3d

该属性包含本地坐标空间中的位置平移。

另请参见 x,y, 和z 。


right : vector3d [read-only]

该属性返回节点在场景空间中右侧方向的归一化矢量。

另请参阅 forward,up, 和mapDirectionToScene 。


rotation : quaternion

该属性包含节点的旋转值。这些值以四元数形式存储。


scale : vector3d

该属性包含 x、y 和 z 轴的比例值。


scenePosition : vector3d [read-only]

该属性返回节点在场景空间中的位置。

注： 有时也称为全局位置。但其含义是 "在 3D 世界中的全局位置"，而不是 "在屏幕或桌面上的全局位置"（这通常是其他 Qt API 的解释）。

注意： 位置将以与节点相同的方向报告。

另请参阅 mapPositionToScene 。


sceneRotation : quaternion [read-only]

该属性返回节点在场景空间中的旋转角度。


sceneScale : vector3d [read-only]

该属性返回节点在场景空间中的缩放比例。


sceneTransform : matrix4x4 [read-only]

此属性返回节点的全局变换矩阵。

注意： 返回值将采用右手坐标。


staticFlags : int

该属性定义了用于评估节点渲染方式的静态标记。目前没有任何作用，只是作为未来实现的占位符。


up : vector3d [read-only]

此属性返回节点在场景空间中向上方向的归一化向量。

另请参阅 forward,right, 和mapDirectionToScene 。


visible : bool

当此属性为 true 时，节点（及其子节点）是可见的。


x : real

该属性包含本地坐标空间中位置平移的 x 值。

另请参阅 position 。


y : real

该属性包含本地坐标空间中位置平移的 y 值。

另请参见 position 。


z : real

该属性包含本地坐标空间中位置平移的 z 值。

另请参阅 position 。


方法文档

vector3d mapDirectionFromNode(QtQuick3D::Node node, vector3d localDirection)

将localDirection 从node 的本地空间平移到此节点的本地空间。返回值不受（继承的）节点比例或位置的影响。

注意： 返回值的长度与localDirection 相同（即未标准化）。

注： 如果node 为空，则localDirection 将按场景空间坐标解释。

另请参阅 mapDirectionToNode,mapDirectionFromScene, 和mapDirectionToScene 。


vector3d mapDirectionFromScene(vector3d sceneDirection)

将sceneDirection 从场景空间转换为本地空间。返回值不受节点（继承的）缩放比例或位置的影响。

注意： 返回值的长度与sceneDirection 相同（即未标准化）。

另请参见 mapDirectionToScene,mapDirectionToNode, 和mapDirectionFromNode 。


vector3d mapDirectionToNode(QtQuick3D::Node node, vector3d localDirection)

将localDirection 从该节点的本地空间转换为node 的本地空间。返回值不受节点的（继承）缩放比例或位置的影响。

注意： 返回值的长度与localDirection 相同（即未标准化）。

注意： 如果node 为空，则返回的方向将转换为场景空间坐标。

另请参阅 mapDirectionFromNode,mapDirectionFromScene, 和mapDirectionToScene 。


vector3d mapDirectionToScene(vector3d localDirection)

将localDirection 从本地空间转换为场景空间。返回值不受节点（继承的）缩放比例或位置的影响。

注意： 返回值的长度与localDirection 相同（即未标准化）。

另请参见 mapDirectionFromScene,mapDirectionToNode, 和mapDirectionFromNode 。


vector3d mapPositionFromNode(QtQuick3D::Node node, vector3d localPosition)

将localPosition 从node 的本地空间转换为该节点的本地空间。

注： 如果node 为空，则localPosition 将按场景空间坐标解释。

另请参阅 mapPositionToScene,mapPositionFromScene, 和mapPositionToNode 。


vector3d mapPositionFromScene(vector3d scenePosition)

将scenePosition 从场景空间转换为本地空间。

另请参阅 mapPositionToScene,mapPositionToNode, 和mapPositionFromNode 。


vector3d mapPositionToNode(QtQuick3D::Node node, vector3d localPosition)

将localPosition 从该节点的本地空间转换为node 的本地空间。

注： 如果node 为空，则localPosition 将转换为场景空间坐标。

另请参阅 mapPositionToScene,mapPositionFromScene, 和mapPositionFromNode 。


vector3d mapPositionToScene(vector3d localPosition)

将localPosition 从本地空间转换到场景空间。

注： "场景空间 "有时也被称为 "全局空间"。但其含义是 "3D 世界中的全局"，而不是 "屏幕或桌面的全局"（这通常是其他 Qt API 的解释）。

另请参见 mapPositionFromScene,mapPositionToNode, 和mapPositionFromNode 。


rotate(real degrees, vector3d axis, enumeration space)

通过给定的degrees ，将此节点围绕axis 旋转。指定的旋转将添加到节点的当前旋转中。轴可以相对于不同的spaces 指定。

常数说明
Node.LocalSpace轴相对于节点的本地方向。
Node.ParentSpace轴相对于父节点的本地方向。
Node.SceneSpace轴线相对于场景。

© 2025 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.