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

Bars3DNode QML Type

3D条形图节点。更多...

Import Statement: import QtGraphs
Inherits:

GraphsNode

属性

信号

方法

详细说明

此类型允许开发者使用Qt Quick 在3D环境中渲染条形图节点。

要使用此类型，您需要导入Qt Graphs 模块：

import QtGraphs

之后，您可以在 QML 文件中使用 Bars3DNode：

import QtQuick
import QtGraphs

View3D {
    width: 640
    height: 480

    Bars3DNode {
        width: parent.width
        height: parent.height

        Bar3DSeries {
            itemLabelFormat: "@colLabel, @rowLabel: @valueLabel"

            ItemModelBarDataProxy {
                itemModel: dataModel
                // Mapping model roles to bar series rows, columns, and values.
                rowRole: "year"
                columnRole: "city"
                valueRole: "expenses"
            }
        }
    }

    ListModel {
        id: dataModel
        ListElement{ year: "2022"; city: "Oulu";     expenses: "4200"; }
        ListElement{ year: "2022"; city: "Rauma";    expenses: "2100"; }
        ListElement{ year: "2022"; city: "Helsinki"; expenses: "7040"; }
        ListElement{ year: "2022"; city: "Tampere";  expenses: "4330"; }
        ListElement{ year: "2023"; city: "Oulu";     expenses: "3960"; }
        ListElement{ year: "2023"; city: "Rauma";    expenses: "1990"; }
        ListElement{ year: "2023"; city: "Helsinki"; expenses: "7230"; }
        ListElement{ year: "2023"; city: "Tampere";  expenses: "4650"; }
    }
}

另请参阅 Bar3DSeries 、ItemModelBarDataProxy 、Scatter3DNode 、Surface3DNode 以及Qt Graphs 等用于3D渲染的C++类。

属性文档

aspectRatio : real

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

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

另请参阅 horizontalAspectRatio 。

barSeriesMargin : size

X 和 Z 维度中系列列之间的间距。默认预设值为(0.0, 0.0) 。合理的取值范围为 [0,1) 。

barSpacing : size

X 和 Z 方向的条形间距。

默认预设值为(1.0, 1.0) 。间距受barSpacingRelative 属性的影响。

barSpacingRelative : bool

间距是绝对的，还是相对于条形厚度而言的。

如果true ，则0.0 的值表示条形图并排排列，1.0 表示条形图之间留有与单个条形图厚度等宽的间距，以此类推。默认值为true 。

barThickness : real

X 方向与 Z 方向之间的棒材厚度比。值1.0 表示棒材的宽度等于其深度，而0.5 则表示棒材的深度是其宽度的两倍。

columnAxis : Category3DAxis

当前活动的列坐标轴。

如果未指定坐标轴，则会创建一个没有标签的临时默认坐标轴。如果显式将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

customItemList : list<Custom3DItem>

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

floorLevel : real

条形图在Y轴数据坐标系中的底线高度。

实际下限将受Y轴最小值和最大值的限制。默认值为零。

gridLineType : Graphs3D.GridLineType

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

此值将影响所有网格线。

另请参阅 Graphs3D.GridLineType 。

horizontalAspectRatio : real

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

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

另请参阅 aspectRatio 、polar 、Bars3DNode::barThickness 以及Bars3DNode::barSpacing 。

labelMargin : real

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

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

另请参阅 QAbstract3DAxis::labelAutoAngle 。

locale : locale

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

另请参阅 Value3DAxis::labelFormat 。

margin : real

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

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

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

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

multiSeriesUniform : bool

指定即使显示了多个系列，条形图是否应根据单个系列条形的比例进行缩放。如果设置为true ，则bar spacing 仅会正确应用于X轴。默认预设为false 。

optimizationHint : Graphs3D.OptimizationHint

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

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

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

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

polar : bool

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

默认值为false 。

另请参阅 radialLabelOffset 。

primarySeries : Bar3DSeries

图表的主系列。当未在坐标轴上显式设置标签时，该系列用于确定行轴和列轴的标签。

如果指定的数据系列尚未添加到图表中，将其设置为主数据系列也会将其隐式地添加到图表中。

如果主数据系列本身从图表中被移除，则此属性将重置为默认值。

如果该数据集为空，则该属性将重置为默认值。默认值为第一个添加的数据集；若图表中未添加任何数据集，则默认值为零。

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 。

rowAxis : Category3DAxis

当前活动的行轴。

如果未指定坐标轴，则会创建一个无标签的临时默认坐标轴。如果显式将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

selectedElement : Graphs3D.ElementType [read-only]

图中选中的元素。

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

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

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

selectedSeries : Bar3DSeries [read-only]

所选系列或null 。如果selectionMode 设置了SelectionMultiSeries 标志，则该属性将包含拥有所选柱状图的系列。

selectionMode : Graphs3D.SelectionMode

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

seriesList : list<Bar3DSeries> [default]

图表的系列。默认情况下，此属性包含一个空列表。要设置系列，可以使用addSeries()函数，或者将其定义为图表的子元素。

theme : GraphsTheme

图表的当前主题。

另请参阅 GraphsTheme 。

valueAxis : ValueAxis3D

活动值轴。

如果未指定坐标轴，系统将创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果显式地将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

信号文档

barSeriesMarginChanged(size margin)

当barSeriesMargin 变为margin 时，将触发此信号。

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

barSpacingChanged(size spacing)

当barSpacing 变为spacing 时，会触发此信号。

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

barSpacingRelativeChanged(bool relative)

当barSpacingRelative 变为relative 时，会触发此信号。

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

barThicknessChanged(real thicknessRatio)

当barThickness 变为thicknessRatio 时，会触发此信号。

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

columnAxisChanged(Category3DAxis axis)

当columnAxis 变为axis 时，会发出此信号。

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

floorLevelChanged(real level)

当floorLevel 变为level 时，会发出此信号。

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

multiSeriesUniformChanged(bool uniform)

当multiSeriesUniform 变为uniform 时，将触发此信号。

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

primarySeriesChanged(Bar3DSeries series)

当primarySeries 变为series 时，会触发此信号。

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

rowAxisChanged(Category3DAxis axis)

当rowAxis 变为axis 时，会触发此信号。

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

selectedSeriesChanged(Bar3DSeries series)

当selectedSeries 变为series 时，会触发此信号。

注意： 对应的处理程序 为onSelectedSeriesChanged 。

valueAxisChanged(ValueAxis3D axis)

当valueAxis 变为axis 时，会触发此信号。

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

方法文档

qsizetype addCustomItem(Custom3DItem item)

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

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

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

void addSeries(Bar3DSeries series)

将series 添加到图表中。一个图表可以包含多个系列，但只能有一组坐标轴，因此所有系列的行和列必须匹配，可视化数据才有意义。 如果图表中有多个可见系列，且未在坐标轴上显式设置标签，则只有第一个添加的系列会在坐标轴上生成行或列标签。如果新添加的系列指定了选定条形，该条形将被高亮显示，且任何现有的选择都将被清除。仅有一个添加的系列可以具有活动选择。

另请参阅 GraphsNode::hasSeries()。

void clearSelection()

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

void doPicking(QPoint point)

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

另请参阅 selectedElement 。

void doRayPicking(QVector3D origin, QVector3D direction)

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

另请参阅 selectedElement 。

bool hasSeries(Abstract3DSeries series)

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

void insertSeries(int index, Bar3DSeries series)

将series 插入到序列列表中的index 位置。如果series 已添加到列表中，则将其移动到新的index 位置。

注意：当 将一个序列移动到位于其旧索引之后的新index 时，列表中的新位置是按序列仍位于旧索引处的假设来计算的，因此最终索引实际上是index 减去1。

另请参阅 GraphsNode::hasSeries()。

void releaseCustomItem(Custom3DItem item)

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

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

另请参阅 Custom3DItem::textureFile 。

void removeCustomItem(Custom3DItem item)

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

void removeCustomItemAt(vector3d position)

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

void removeCustomItems()

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

void removeSeries(Bar3DSeries series)

从图中移除series 。

另请参阅 GraphsNode::hasSeries()。

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 。

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