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

GraphsItem3D QML Type

3D 图表的基础类型。更多...

Import Statement: import QtGraphs
Inherited By:

Bars3D, Scatter3D, and Surface3D

属性

信号

方法

详细说明

QtGraphs 中所有 3D 图的不可创建基本类型。

另请参阅 Bars3D 、Scatter3D 、Surface3D 以及Qt Graphs 中的 3D C++ 类。

属性文档

ambientLightStrength : real

整个图表的环境光强度。该值决定了无论光源位置如何，图表中各处的颜色显示是否均匀且明亮。该值必须在0.0 和1.0 之间。

aspectRatio : real

图表中水平平面最长轴与y轴之间的缩放比例。默认值为2.0 。

注意：此设置 对Bars3D 无影响。

另请参阅 horizontalAspectRatio 。

cameraPreset : Graphs3D.CameraPreset

当前激活的相机预设，该预设属于Graphs3D.CameraPreset 之一。如果未激活任何预设，则该值为Graphs3D.CameraPreset.NoPreset 。

cameraTargetPosition : vector3d

摄像机目标以 Vector3d 形式表示。默认值为vector3d(0.0, 0.0, 0.0) 。

有效的坐标值范围为-1.0...1.0 ，其中边界值表示相应轴范围的边界。超出此范围的任何值都会被限制在边界值内。

cameraXRotation : real

相机以目标点为轴，从当前基准位置开始的X轴旋转角度（单位：度）。

cameraYRotation : real

相机以目标点为轴，从当前基点位置开始的Y轴旋转角度（单位：度）。

cameraZoomLevel : real

摄像机的缩放级别（以百分比表示）。默认值100.0 表示摄像机未设置任何缩放。该值受minCameraZoomLevel 和maxCameraZoomLevel 属性的限制。

另请参阅 minCameraZoomLevel 和maxCameraZoomLevel 。

currentFps : int

启用帧率（FPS）测量后，过去一秒的测量结果将存储在此只读属性中。在测量功能激活后，该值至少需要一秒钟才会更新。

另请参阅 measureFps 。

customItemList : list<Custom3DItem>

添加到图中的Custom3DItem 项的列表。图将接管这些已添加项的所有权。

cutoffMargin : real [since 6.11]

用于确定轴限值与图表元素被剔除的位置之间差值的数值。

注意：不 影响条形图。

该属性自 Qt 6.11 起引入。

dragMode : Graphs3D.DragMode [since 6.12]

确定如何解释图形上的拖动事件，取值范围为 Graphs3D.DragMode 枚举的某个值。

默认值为Graphs3D.DragMode.Rotate 。

该属性在 Qt 6.12 中引入。

另请参阅 panEnabled 。

gridLineType : Graphs3D.GridLineType

用于指定网格线类型是Graphs3D.GridLineType.Shader 还是Graphs3D.GridLineType.Geometry 。

此值将影响所有网格线。

另请参阅 Graphs3D.GridLineType 。

horizontalAspectRatio : real

x 轴与 z 轴之间图表缩放的比例。0.0 表示根据轴范围自动缩放。默认值为0.0 。

注意：此属性 对Bars3D无效 ，后者通过barThickness 和barSpacing 属性处理水平面的缩放。极坐标图也会忽略此属性。

另请参阅 aspectRatio 、polar 、Bars3D::barThickness 和Bars3D::barSpacing 。

labelMargin : real

此属性用于指定坐标轴标签的放置边距。

负值将标签放置在绘图区域内，而正值将标签放置在绘图区域外。当值为负时，标签的自动旋转功能将被禁用。默认值为0.1

另请参阅 QAbstract3DAxis::labelAutoAngle 。

lightColor : color

在Scene3D 中定义的环境光和镜面光颜色。

lightStrength : real

整个图形的镜面光强度。该值必须介于0.0 和10.0 之间。

该值会影响在Scene3D 中指定的光照效果。

locale : locale

设置用于格式化各种数字标签的区域设置。默认使用"C" 区域设置。

另请参阅 Value3DAxis::labelFormat 。

margin : real

用于确定可绘制图表区域边缘与图表背景边缘之间留白空间的绝对值。

如果边距值为负数，则边距将由系统自动确定，并可能根据数据系列中数据点的大小和图表类型而变化。如果图表的纵横比未从默认值进行更改，该值将被解释为 y 轴范围的百分比。默认值为-1.0 。

注意：若 为散点图设置的 边距小于自动确定的边距，可能会导致图表边缘处的散点与图表背景重叠。

注意：在 散点图和曲面图中 ，如果边距相对于坐标轴标签的大小较小，则会调整坐标轴边缘标签的位置，以避免与相邻坐标轴的边缘标签发生重叠。

maxCameraXRotation : real [since 6.9]

相机围绕目标点的最大X轴旋转角度（单位：度）。默认值为180.0

该属性自 Qt 6.9 起引入。

maxCameraYRotation : real [since 6.9]

相机围绕目标点的最大Y轴旋转角度（单位：度）。默认值为90.0

该属性自 Qt 6.9 起引入。

maxCameraZoomLevel : real

设置相机允许的最大缩放级别。如果新的最大级别低于现有的最小级别，则最小级别也会调整为新的最大级别。如果当前的cameraZoomLevel 超出了新范围，也会进行相应调整。默认值为500.0f 。

另请参阅 cameraZoomLevel 和minCameraZoomLevel 。

measureFps : bool

如果true ，则渲染将持续进行，而非按需进行，并且currentFps 属性的值也会随之更新。默认值为false 。

另请参阅 currentFps 。

minCameraXRotation : real [since 6.9]

相机围绕目标点的最小X轴旋转角度（单位：度）。默认值为-180.0

该属性自 Qt 6.9 起引入。

minCameraYRotation : real [since 6.9]

相机围绕目标点的最小Y轴旋转角度（单位：度）。默认值为0.0

该属性自 Qt 6.9 起引入。

minCameraZoomLevel : real

设置允许的最小相机缩放级别。如果新的最小级别高于现有的最大级别，则最大级别也会调整为新的最小级别。如果当前的cameraZoomLevel 超出了新范围，它也会被相应调整。minCameraZoomLevel不能设置为低于1.0 。默认值为10.0 。

另请参阅 cameraZoomLevel 和maxCameraZoomLevel 。

msaaSamples : int

当renderingMode 为Indirect 时，多采样抗锯齿所使用的采样数即为该值。当renderingMode 为DirectToBackground 时，该属性值为只读，并返回窗口表面格式所指定的采样数。默认值为4 。

另请参阅 renderingMode 。

optimizationHint : Graphs3D.OptimizationHint

指定渲染优化时使用默认模式还是传统模式。

默认模式采用实例化渲染，可在大多数系统上以最佳性能提供完整的功能集。静态模式可优化图渲染，非常适合大型且数据不变的集合。但在数据动态变化和项目旋转时，其渲染速度会变慢。 选择操作未经过优化，因此不建议在海量数据集上使用静态模式。传统模式会单独渲染图中的所有项目，而不使用实例化。仅当默认模式无法正常工作时才应使用该模式，这相当于目标系统不支持实例化。默认值为Default 。

注意：在 某些环境下 ，使用静态优化的庞大图可能无法渲染，因为所有项均通过单次绘制调用进行渲染，而不同的图形驱动程序对每次调用的最大顶点数支持不同。此问题主要出现在 32 位和 OpenGL ES2 平台上。 要解决此问题，请选择顶点数较少的项网格，或使用点网格。

另请参阅 Abstract3DSeries::mesh 和Graphs3D.OptimizationHint 。

orthoProjection : bool

如果设置为true ，则将使用正射投影来显示图形。默认值为false 。

注意： 当设置为true 时，阴影 将被禁用。

panEnabled : bool [since 6.12]

该输入处理程序是否允许对图进行平移。

默认值为true 。

该属性在 Qt 6.12 中引入。

polar : bool

如果true ，则横轴将变为极坐标轴。x轴变为角轴，z轴变为半径轴。极坐标模式不适用于条形图。

默认值为false 。

另请参阅 orthoProjection 和radialLabelOffset 。

queriedGraphPosition : vector3d [read-only]

此只读属性包含通过 `Scene3D::graphPositionQuery` 查询得到的、沿每个轴的最新图表位置值。这些值已归一化至范围 `[-1, 1]`。如果查询的位置超出图表边界，则这些值不会反映实际位置，而是会显示为范围 `[-1, 1]` 之外的某个未定义位置。在进行查询之前，该值将保持未定义状态。

由于不存在与特定屏幕位置完全对应的唯一正确 3D 坐标，因此为了保持一致性，查询始终针对包围图表的不可见矩形的内侧进行。

注意：条形图 仅允许在图表底部高度处查询位置，因此条形图的 y 值始终为零，且只有包含图表底部的屏幕位置才能进行有效的查询。

另请参阅 Scene3D::graphPositionQuery 。

radialLabelOffset : real

该属性指定径向极坐标轴轴标的标准水平偏移量。值0.0 表示应将轴标绘制在0角度的角坐标轴网格线旁。值1.0 表示轴标绘制在其通常位置，即图表背景的边缘。如果polar属性的值为false ，则该属性将被忽略。默认值为1.0 。

另请参阅 polar 。

renderingMode : Graphs3D.RenderingMode

图的渲染方式。默认值为Indirect 。

注意：设置 图表的 `antialiasing ` 属性不会产生任何效果。但是，如果当前的渲染模式使用了抗锯齿，则该属性会由图表自身自动设置。

另请参阅 msaaSamples 和Graphs3D.RenderingMode 。

rootNode : Node [read-only, since 6.9]

返回指向 3D 图根节点的指针。使用此属性可通过 `importScene` 将 3D 图注入到单独的 `View3D ` 中：

Bars3D {
  id: bars
}
View3D {
  importScene: bars.rootNode
}

该属性于 Qt 6.9 中引入。

另请参阅 View3D 。

rotationEnabled : bool

该输入处理程序是否允许图形旋转。

默认值为true 。

scene : Scene3D [read-only]

Scene3D 指针，可用于操作场景并访问场景元素。

该属性为只读。

selectedElement : Graphs3D.ElementType [read-only]

图中选中的元素。

该属性可用于查询所选元素的类型。该类型在图表中进行新选择并发出selectedElementChanged 信号之前一直有效。

该信号可用于实现自定义输入处理，例如“轴处理”示例中所示。

另请参阅 selectedLabelIndex()、selectedAxis()、selectedCustomItemIndex()、selectedCustomItem()、Bars3D::selectedSeries 、Scatter3D::selectedSeries 、Scene3D::selectionQueryPosition 以及Graphs3D.ElementType 。

selectionEnabled : bool

该输入处理程序是否允许从图中进行选择。

默认值为true 。

selectionMode : Graphs3D.SelectionMode

图形中的活动选择模式。Graphs3D.SelectionFlag 枚举值之一。

shadowQuality : Graphs3D.ShadowQuality

阴影质量。Graphs3D.ShadowQuality 枚举值之一。

shadowStrength : real

整个图形的阴影强度。数值越大，阴影越深。该值必须在0.0 和100.0 之间。

该值会影响在Scene3D 中指定的光照效果。

theme : GraphsTheme

图表的当前主题。

另请参阅 GraphsTheme 。

transparencyTechnique : Graphs3D.TransparencyTechnique [since 6.9]

指定要使用的透明度处理方式。默认值为Default 。渲染透明曲面图时，请使用Approximate 或Accurate 。对于其他图类型，应使用Default 。

常量描述
Default表示不使用与顺序无关的透明度技术。可提供最佳性能。当图表不包含透明度，或者条形图或散点图同时使用实例化时（即optimizationHint 为{QtGraphs3D::OptimizationHint::Default}），请使用此选项。
Approximate表示图将尝试近似实现顺序无关透明度。此方法比 `Accurate ` 更快，且可在较旧的硬件上运行，但可能会产生不准确的结果。当需要顺序无关透明度，但性能开销必须低于使用精确顺序无关透明度时，请使用此方法。
Accurate表示使用精确的顺序无关透明度。当需要完美的透明度渲染时请使用此选项。

该属性在 Qt 6.9 中引入。

wrapCameraXRotation : bool

X 轴旋转中最小值和最大值的处理方式。默认情况下，X 轴旋转会从最小值循环到最大值，再从最大值循环回最小值。

若设置为true ，相机的X轴旋转将在最小值和最大值之间循环；若设置为false ，相机的X轴旋转将仅限于由最小值和最大值确定的扇区范围内。

wrapCameraYRotation : bool

Y 轴旋转中最小值和最大值的限制行为。默认情况下，Y 轴旋转在最小值和最大值之间受限，且不循环。

如果true ，则相机的 Y 轴旋转会从最小值循环到最大值，再从最大值循环到最小值。如果false ，则相机的 Y 轴旋转将限制在由最小值和最大值确定的扇形区域内。

zoomAtTargetEnabled : bool

是否应在缩放时更改摄像头目标，以便图表中被缩放的点在缩放后仍保持在原位置。

默认值为true 。

zoomEnabled : bool

该输入处理程序是否允许对图表进行缩放。

默认值为true 。

Signal 文档

doubleTapped(QEventPoint eventPoint, Qt::MouseButton button)

当在短时间内连续点击图形项两次时，会触发此信号。eventPoint 信号参数包含来自释放事件的关于被点击点的信息，而button 则是被点击的mouse button ，或在触摸屏上为NoButton 。

注意： 相应的处理程序 是onDoubleTapped 。

另请参阅 QEventPoint 、Qt::MouseButtons 以及TapHandler::doubleTapped 。

dragged(QVector2D delta)

当执行捏合手势时，如果图形上点簇的平移位置发生变化，则会发出此信号。delta 向量表示平移量的变化。

注意： 相应的处理程序 为onDragged 。

另请参阅 PinchHandler::translationChanged 。

longPressed()

当“parent ”控件被按下并长按的时间超过TapHandler::longPressThreshold 时，会发出此信号。

注意： 相应的处理程序 是onLongPressed 。

另请参阅 TapHandler::longPressed 。

mouseMove(QPoint mousePos)

当图接收到 mouseMove 事件时，会触发此信号。mousePos 值表示鼠标移动时的位置。

注意： 对应的处理程序 是 `onMouseMove`。

另请参阅 QQuickItem::mouseMoveEvent 。

pinch(qreal delta)

当执行捏合手势时，如果图表上的缩放因子发生变化，则会发出此信号。delta 的值表示缩放因子的乘法变化量。

注意： 相应的处理函数 为onPinch 。

另请参阅 PinchHandler::scaleChanged 。

tapped(QEventPoint eventPoint, Qt::MouseButton button)

当图形项被点击一次时，会发出此信号。eventPoint 信号参数包含来自释放事件的、关于被点击点的信息，而button 表示被点击的mouse button ，或在触摸屏上为NoButton 。

注意： 相应的处理程序 为onTapped 。

另请参阅 QEventPoint 、Qt::MouseButtons 和TapHandler::singleTapped 。

wheel(QQuickWheelEvent *event)

每当图表接收到类型为QWheelEvent 的event 时，都会触发此信号：也就是说，每次滚轮移动或滚动手势更新时都会触发。

注意： 相应的处理程序 是onWheel 。

另请参阅 WheelEvent 和WheelHandler::wheel 。

方法文档

qsizetype addCustomItem(Custom3DItem item)

向图中添加一个Custom3DItem item 。图将拥有该添加项的所有权。

若添加成功，则返回所添加项的索引；若尝试添加空项，则返回-1；若尝试添加已存在的项，则返回该项的索引。

另请参阅 removeCustomItems()、removeCustomItem() 和removeCustomItemAt()。

void clearSelection()

清除所有关联系列中的选中项。

void doPicking(QPoint point)

使用来自point 的视图坐标对图中的元素进行点选，并选择第一个被击中的项目。默认的输入处理机制会在接收到 onTapped 事件时执行此操作。

另请参阅 selectedElement 。

void doRayPicking(QVector3D origin, QVector3D direction)

从origin 开始，在direction 中对图的元素进行选择操作，并选取第一个匹配的项目。

另请参阅 selectedElement 。

bool hasSeries(Abstract3DSeries series)

返回“series ”是否已添加到图中。

void releaseCustomItem(Custom3DItem item)

取回对“item ”的所有权，并将“item ”从图中移除。

注意：如果 将同一项重新添加到图形中，则需要重新设置纹理文件。

另请参阅 Custom3DItem::textureFile 。

void removeCustomItem(Custom3DItem item)

删除自定义item 。并删除分配给它的资源。

void removeCustomItemAt(vector3d position)

删除position 下的所有自定义项目。并释放分配给这些项目的资源。

void removeCustomItems()

删除所有自定义项目。并释放分配给这些项目的资源。

Abstract3DAxis selectedAxis()

可用于在接收到selectedElementChanged 信号后获取所选轴，该信号的标签类型不限。该选择在收到下一个selectedElementChanged 信号之前一直有效。

返回所选轴，或返回 null。

另请参阅 selectedElement 。

Custom3DItem selectedCustomItem()

可在接收到类型为ElementType.CustomItem 的selectedElementChanged 信号后，用于获取所选的自定义项。该项的所有权仍归图所有。选定状态将保持有效，直至接收到下一个selectedElementChanged 信号。

返回所选的自定义项，或 null。

另请参阅 selectedElement 。

qsizetype selectedCustomItemIndex()

可在接收到类型为ElementType.CustomItem 的selectedElementChanged 信号后，用于查询所选自定义项的索引。该选择在收到下一个selectedElementChanged 信号之前一直有效。

返回所选自定义项的索引，或 -1。

另请参阅 selectedElement 。

int selectedLabelIndex()

可在接收到selectedElementChanged 信号后，用于查询所选标签的索引，支持任何标签类型。该选择在收到下一个selectedElementChanged 信号之前一直有效。

返回所选标签的索引，或 -1。

另请参阅 selectedElement 。

void setDefaultInputHandler()

* * @brief 恢复默认的输入处理机制。 * * 此方法将重新启用内部预定义的输入处理程序。 * 若之前曾调用 *unsetDefaultInputHandler ，请使用此方法恢复默认行为。 * *

另请参阅 unsetDefaultInputHandler()。

void setDragButton(Qt::MouseButtons button)

* * @brief 设置用于触发拖动事件的鼠标按钮。 * * 该方法允许将启动 * 拖动操作所需的鼠标按钮更改为button 。 * 默认值为Qt::RightButton 。

[since 6.12] void setPanButton(Qt::MouseButtons button)

* * * @brief 设置用于触发平移事件的鼠标按钮。 * * 此方法允许将启动拖动操作所需的鼠标按钮更改为 *button 。 * 默认值为Qt::MiddleButton 。

该方法在 Qt 6.12 中引入。

void unsetDefaultDragHandler()

* * @brief 禁用默认的拖动事件处理程序。 * * 这会专门取消对拖动手势的内置响应。 * 如果您需要为拖动操作实现自定义处理程序，请使用此选项。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultInputHandler()

* * @brief 禁用默认输入处理机制。 * * 此方法将停用所有预定义的默认输入处理程序。 * 若需覆盖默认行为，请调用此方法。 *

另请参阅 unsetDefaultTapHandler()、unsetDefaultDragHandler()、unsetDefaultWheelHandler()，以及unsetDefaultPinchHandler()。

void unsetDefaultPinchHandler()

* * @brief 禁用默认的捏合手势处理程序。 * * 这会专门取消对捏合手势的内置响应。 * 用于实现自定义捏合手势处理程序。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultTapHandler()

* * @brief 禁用默认的点击事件处理程序。 * * 这会专门取消对点击或单击事件的内置响应， * 从而允许实现自定义的点击处理逻辑。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultWheelHandler()

* * @brief 禁用默认的鼠标滚轮事件处理程序。 * * 这会专门取消对鼠标滚轮滚动操作的内置响应。 * 在实现自定义滚轮行为时请使用此选项。 *

另请参阅 unsetDefaultInputHandler()。

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