Back to Qt.io
Contact Us Blog Download Qt
本页内容

Node QML Type

存在于3D场景中的对象的基础组件。更多...

Import Statement: import QtQuick3D
Inherits:

Object3D

Inherited By:
36 types

Affector3D, Attractor3D, AxisHelper, Camera, CustomCamera, DirectionalLight, FrustumCamera, Gravity3D, InstanceRepeater, Joint, Light, Loader3D, LodManager, LookAtNode, Model, OrthographicCamera, ParticleEmitter3D, ParticleSystem3D, PerspectiveCamera, PointLight, PointRotator3D, ReflectionProbe, Repeater3D, Repeller3D, RuntimeLoader, ScaleAffector3D, Skeleton, SpotLight, TrailEmitter3D, Wander3D, XrCamera, XrController, XrHandModel, XrItem, XrOrigin, and XrView

属性

方法

详细说明

Node 类型是其他空间类型的基类，例如Model 、Camera 、Light 。这些对象表示存在于 3D 场景中的实体，因为它们在 3D 空间中具有位置和其他属性。 除根节点外，所有 Node 类型均相对于其父节点进行变换，即在本地坐标系中进行变换。在许多方面，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 轴的旋转值。这些值以 vector3d 形式存储。旋转顺序默认为 ZXY。

另请参阅 QQuaternion::fromEulerAngles()。

forward : vector3d [read-only]

该属性返回一个归一化向量，表示节点在场景空间中的正向方向。

另请参阅 up 、right 以及mapDirectionToScene 。

layers : int

该属性定义了该节点所属的内容图层。这些图层可用于将相关节点分组，例如以便共同渲染或从渲染中过滤掉。在活动Camera 上设置此属性将导致摄像机仅渲染属于指定图层的节点。该值为位掩码，其中每个位代表一个图层。

默认情况下，节点会被分配到main 层，即ContentLayer.Layer0 。

注意：layers属性 不具有继承性；在节点上设置该属性 不会将值从父节点传播到子节点。每个节点都保持自己的图层分配，必须单独设置。

另请参阅 ContentLayer 。

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 。

void rotate(real degrees, vector3d axis, enumeration space)

将该节点围绕axis 轴，以给定的degrees 进行旋转。指定的旋转角度将叠加到节点的当前旋转角度上。轴可以相对于不同的space进行指定。

常量描述
Node.LocalSpace轴相对于该节点的本地方向。
Node.ParentSpace轴相对于该节点的本地方向。
Node.SceneSpace轴相对于场景。

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