QBarSeries Class
QBarSeries 类用于以条形图形式展示数据。更多内容...
| 头文件： | #include <QBarSeries> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Graphs) target_link_libraries(mytarget PRIVATE Qt6::Graphs) |
| qmake： | QT += graphs |
| 在 QML 中： | BarSeries |
| 继承自： | QAbstractSeries |
- 所有成员列表（包括继承的成员）
- QBarSeries 属于Qt Graphs 的2D C++ 类。
公共类型
| enum class | BarsType { Groups, Stacked, StackedPercent } |
| enum class | LabelsPosition { Center, InsideEnd, InsideBase, OutsideEnd } |
属性
|
|
公共函数
| QBarSeries(QObject *parent = nullptr) | |
| bool | append(QBarSet *set) |
| bool | append(const QList<QBarSet *> &sets) |
| QBarSet * | at(qsizetype index) |
| QQmlComponent * | barDelegate() const |
| QList<QBarSet *> | barSets() const |
| qreal | barWidth() const |
| QBarSeries::BarsType | barsType() const |
| QList<QColor> | borderColors() const |
| void | clear() |
| qsizetype | count() const |
| qsizetype | find(QBarSet *set) const |
| bool | insert(qsizetype index, QBarSet *set) |
| qreal | labelsAngle() const |
| QString | labelsFormat() const |
| qreal | labelsMargin() const |
| QBarSeries::LabelsPosition | labelsPosition() const |
| int | labelsPrecision() const |
| bool | labelsVisible() const |
| bool | remove(QBarSet *set) |
| bool | remove(qsizetype index) |
| void | removeMultiple(qsizetype index, qsizetype count) |
| bool | replace(const QList<QBarSet *> &sets) |
| bool | replace(QBarSet *oldValue, QBarSet *newValue) |
| void | replace(qsizetype index, QBarSet *set) |
| QList<QColor> | seriesColors() const |
| void | setBarDelegate(QQmlComponent *newBarDelegate) |
| void | setBarWidth(qreal width) |
| void | setBarsType(QBarSeries::BarsType type) |
| void | setBorderColors(const QList<QColor> &newBorderColors) |
| void | setLabelsAngle(qreal angle) |
| void | setLabelsFormat(const QString &format) |
| void | setLabelsMargin(qreal margin) |
| void | setLabelsPosition(QBarSeries::LabelsPosition position) |
| void | setLabelsPrecision(int precision) |
| void | setLabelsVisible(bool visible = true) |
| void | setSeriesColors(const QList<QColor> &newSeriesColors) |
| bool | take(QBarSet *set) |
重新实现的公共函数
| virtual QAbstractSeries::SeriesType | type() const override |
信号
| void | barDelegateChanged() |
| void | barSetsChanged() |
| void | barWidthChanged() |
| void | barsTypeChanged(QBarSeries::BarsType type) |
| void | barsetsAdded(const QList<QBarSet *> &sets) |
| void | barsetsRemoved(const QList<QBarSet *> &sets) |
| void | borderColorsChanged() |
| void | countChanged() |
| void | labelsAngleChanged(qreal angle) |
| void | labelsFormatChanged(const QString &format) |
| void | labelsMarginChanged(qreal margin) |
| void | labelsPositionChanged(QBarSeries::LabelsPosition position) |
| void | labelsPrecisionChanged(int precision) |
| void | labelsVisibleChanged(bool visible) |
| void | seriesColorsChanged() |
| void | setValueAdded(qsizetype index, qsizetype count, QBarSet *barset) |
| void | setValueChanged(qsizetype index, QBarSet *barset) |
| void | setValueRemoved(qsizetype index, qsizetype count, QBarSet *barset) |
| void | updatedBars() |
详细说明
该类默认将数据绘制为按类别分组的条形图系列，每个条形图集中的每个类别都会向该系列添加一个条形。它还支持水平条形图，并支持将条形图分组为堆叠条形图。
条形系列需要将GraphsView 的x轴设置为BarCategoryAxis ，并将y轴设置为ValueAxis 。
另请参阅 QBarSet 和QAbstractSeries 。
成员类型文档
enum class QBarSeries::BarsType
此枚举值描述了柱形系列的类型：
| 常量 | 值 | 描述 |
|---|---|---|
QBarSeries::BarsType::Groups | 0 | 条形图集按类别分组。 |
QBarSeries::BarsType::Stacked | 1 | 条形图集按类别依次堆叠。 |
QBarSeries::BarsType::StackedPercent | 2 | 条形图组按类别依次堆叠显示。每个区段的大小与其值占堆叠中所有区段总值的比例相对应。 |
enum class QBarSeries::LabelsPosition
此枚举值描述了数据值标签的位置：
| 常量 | 值 | 描述 |
|---|---|---|
QBarSeries::LabelsPosition::Center | 0 | 标签位于条形图的中央。 |
QBarSeries::LabelsPosition::InsideEnd | 1 | 标签位于条形上方。 |
QBarSeries::LabelsPosition::InsideBase | 2 | 标签位于条形图内部的底部。 |
QBarSeries::LabelsPosition::OutsideEnd | 3 | 标签位于条形上方外部。 |
属性文档
barDelegate : QQmlComponent*
该属性包含一个用于可视化各条柱状图的自定义 QML 组件。每个柱状图都会创建该组件的一个实例。若未定义该属性，则使用柱状图的默认矩形可视化效果。
该组件可用的动态属性包括：
| 类型 | 名称 | 描述 |
|---|---|---|
| QColor | barColor | 条形的填充颜色。该值取自QGraphsTheme ，若QBarSet 覆盖了颜色，则取自QBarSet::color 。 |
| QColor | barBorderColor | 条形图的边框颜色。该值来自QGraphsTheme ，若QBarSet 覆盖了颜色，则来自QBarSet::borderColor 。 |
| qreal | barBorderWidth | 条形边框的宽度。该值来自QGraphsTheme ，或者在QBarSet 覆盖宽度时来自QBarSet::borderWidth 。 |
| qreal | barValue | 条形图的数值。该值来自QBarSet::values 。 |
| QString | barLabel | 柱形的标签。该值来自QBarSet::label 。 |
| bool | barSelected | 当条形被选中时，此值为 true，这意味着该条形的索引在QBarSet::selectedBars 中。 |
| int | barIndex | K线索引，范围从 0 到总K线数减 1。[自 6.9 起] |
要使用这些属性，请在自定义组件中添加名称与之对应的属性。例如"property color barColor" 和"property real barValue" 。
访问函数：
| QQmlComponent * | barDelegate() const |
| void | setBarDelegate(QQmlComponent *newBarDelegate) |
Notifier 信号：
| void | barDelegateChanged() |
[read-only] barSets : QList<QBarSet *>
该属性保存了添加到序列中的集合列表。
访问函数：
| QList<QBarSet *> | barSets() const |
通知信号：
| void | barSetsChanged() |
barWidth : qreal
该属性用于指定该数据系列中柱状图的宽度。
宽度的单位即为 x 轴的单位。柱形的最小宽度为零，负值将被视为零。将宽度设置为零意味着，无论 x 轴的比例如何，屏幕上柱形的宽度均为 1 像素。宽度大于零的柱形将根据 x 轴的比例进行缩放。
默认情况下，barWidth 的值为 0.5（条形将占据可用宽度的 50%）。有效值范围为 0.0（0%）到 1.0（100%）。
注意：当与 QBarSeries配合使用时， 此值指定的是一组柱状图的宽度，而非单个柱状图的宽度。
访问函数：
| qreal | barWidth() const |
| void | setBarWidth(qreal width) |
通知信号：
| void | barWidthChanged() |
另请参阅 QBarSeries 。
barsType : BarsType
该属性存储柱形图系列的类型。
访问函数：
| QBarSeries::BarsType | barsType() const |
| void | setBarsType(QBarSeries::BarsType type) |
通知信号：
| void | barsTypeChanged(QBarSeries::BarsType type) |
borderColors : QList<QColor>
该属性存储了系列中所有对象将使用的边框颜色列表。
如果系列数量多于颜色数量，颜色列表将循环显示，并从列表中的第一种颜色开始重新显示。如果未设置此属性（默认情况），则将使用QGraphsTheme::borderColors 中的颜色。
访问函数：
| QList<QColor> | borderColors() const |
| void | setBorderColors(const QList<QColor> &newBorderColors) |
通知信号：
| void | borderColorsChanged() |
[read-only] count : qsizetype
该属性保存条形图系列中的条形集数量。
访问函数：
| qsizetype | count() const | [see note below] |
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
通知信号：
| void | countChanged() |
labelsAngle : qreal
该属性存储值标签的角度（单位为度）。
访问函数：
| qreal | labelsAngle() const |
| void | setLabelsAngle(qreal angle) |
通知信号：
| void | labelsAngleChanged(qreal angle) |
labelsFormat : QString
此属性用于指定条形系列中标签的显示格式。
QBarSeries 支持以下格式标记：
| @value | 条形图的数值 |
例如，以下格式标签的使用方式将生成先显示数值、后显示单位（u）的标签：
series->setLabelsFormat("@value u");默认情况下，标签显示柱形的数值。对于百分比柱形系列，数值后会添加%。标签显示在绘图区域中，如果柱形彼此靠近，标签可能会重叠。
访问函数：
| QString | labelsFormat() const |
| void | setLabelsFormat(const QString &format) |
通知信号：
| void | labelsFormatChanged(const QString &format) |
另请参阅 labelsVisible 、labelsPosition 以及labelsPrecision 。
labelsMargin : qreal
该属性用于设置数值标签的边距（单位为像素）。
当labelsPosition 的设置值不是LabelsPosition.Center 时，将使用此侧边距。默认值为0 。
访问函数：
| qreal | labelsMargin() const |
| void | setLabelsMargin(qreal margin) |
通知信号：
| void | labelsMarginChanged(qreal margin) |
labelsPosition : LabelsPosition
该属性用于指定值标签的位置。
访问函数：
| QBarSeries::LabelsPosition | labelsPosition() const |
| void | setLabelsPosition(QBarSeries::LabelsPosition position) |
通知信号：
| void | labelsPositionChanged(QBarSeries::LabelsPosition position) |
另请参阅 labelsVisible 和labelsFormat 。
labelsPrecision : int
此属性用于指定值标签中显示的有效数字位数上限。
默认值为 6。
访问函数：
| int | labelsPrecision() const |
| void | setLabelsPrecision(int precision) |
通知信号：
| void | labelsPrecisionChanged(int precision) |
labelsVisible : bool
此属性控制条形系列中标签的可见性。标签的默认可见性为false 。
注意： 默认标签 仅显示该集合的数值。您可以通过barDelegate 创建自定义标签。
访问函数：
| bool | labelsVisible() const |
| void | setLabelsVisible(bool visible = true) |
通知信号：
| void | labelsVisibleChanged(bool visible) |
另请参阅 ` barDelegate`。
seriesColors : QList<QColor>
该属性存储了系列中所有对象将使用的基础颜色列表。
如果系列数量多于颜色数量，颜色列表将循环显示，并从列表中的第一种颜色开始重复。如果未设置此属性（默认情况），则将使用QGraphsTheme::seriesColors 中的颜色。
访问函数：
| QList<QColor> | seriesColors() const |
| void | setSeriesColors(const QList<QColor> &newSeriesColors) |
通知信号：
| void | seriesColorsChanged() |
成员函数文档
[explicit] QBarSeries::QBarSeries(QObject *parent = nullptr)
构建一个空的条形图系列，该系列是QObject 类型，并且是parent 的子节点。
[invokable] bool QBarSeries::append(QBarSet *set)
将由set 指定的柱形图集合添加到柱形图系列中，并接管该集合的所有权。如果该集合为空，或者它已经属于该系列，则不会将其追加。如果追加成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
[invokable] bool QBarSeries::append(const QList<QBarSet *> &sets)
将由 `sets ` 指定的柱状图集合列表添加到柱状图序列中，并接管这些集合的所有权。 如果所有集合均已成功追加，则返回true 。如果任何集合为null或此前已被追加到该系列中，则不会追加任何内容，且本函数返回false 。如果列表中出现任何重复的集合，则不会追加任何内容，且本函数返回false 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] QBarSet *QBarSeries::at(qsizetype index)
检索位于index 位置处指定的BarSet 。如果未找到BarSet ，则返回 null。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
QList<QBarSet *> QBarSeries::barSets() const
返回一个条形系列中的条形集列表。保留对这些条形集的所有权。
注意： 这是 barSets 属性的获取器 函数。
qreal QBarSeries::barWidth() const
返回该系列柱状图的柱宽。
注意： 这是 barWidth 属性的获取 函数。
另请参阅 setBarWidth()。
[signal] void QBarSeries::barsetsAdded(const QList<QBarSet *> &sets)
当将sets 中指定的K线添加到该系列时，会发出此信号。
[signal] void QBarSeries::barsetsRemoved(const QList<QBarSet *> &sets)
当系列中移除了由sets 指定的柱状图时，将发出此信号。
另请参阅 remove()。
[invokable] void QBarSeries::clear()
从该系列中移除所有柱状图集，并将其永久删除。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] qsizetype QBarSeries::count() const
返回柱形图系列中的柱形组数量。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
注意： 这是属性 count 的获取 函数。
[invokable] qsizetype QBarSeries::find(QBarSet *set) const
返回根据set 定义的第一个BarSet 的索引。如果未找到BarSet ，则返回 -1。
注意： 可通过元对象系统和从 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] bool QBarSeries::insert(qsizetype index, QBarSet *set)
将由set 指定的条形集插入到系列中，位置由index 指定，并取得该集的所有权。如果该集为空或已属于该系列，则不会将其追加。若插入成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
bool QBarSeries::labelsVisible() const
返回标签的可见性。
注意： 这是属性 labelsVisible 的获取器 函数。
另请参阅 ` setLabelsVisible()`。
[signal] void QBarSeries::labelsVisibleChanged(bool visible)
当标签的可见性变为visible 时，会触发此信号。
注意： 这是属性labelsVisible 的Notifier 信号。
另请参阅 labelsVisible() 和setLabelsVisible()。
[invokable] bool QBarSeries::remove(QBarSet *set)
从系列中移除由 `set ` 指定的柱形集，如果移除成功，则将其永久删除。如果该柱形集已被移除，则返回 `true `。
注意： 可通过元对象系统以及从 QML 中调用此 函数。参见Q_INVOKABLE 。
[invokable] bool QBarSeries::remove(qsizetype index)
删除位于index 位置的BarSet 。该BarSet 将被永久删除。
注意：此 函数可通过元对象系统及从 QML 中调用。参见Q_INVOKABLE 。
[invokable] void QBarSeries::removeMultiple(qsizetype index, qsizetype count)
从index 开始，移除该系列中数量为count 的多个BarSet。这些BarSet将被永久删除。
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
[invokable] bool QBarSeries::replace(const QList<QBarSet *> &sets)
将此BarSeries 中的整个BarSet 列表替换为sets 中指定的BarSets。所有原始的BarSets都将被永久删除。如果所有BarSets均已被替换，则返回true 。
注意：此 函数可通过元对象系统及从 QML 中调用。参见Q_INVOKABLE 。
[invokable] bool QBarSeries::replace(QBarSet *oldValue, QBarSet *newValue)
将由oldValue 指定的BarSet 替换为newValue 中的内容。如果在该系列中找到了oldValue 中的BarSet ，则将其永久删除。如果替换成功，则返回true 。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
[invokable] void QBarSeries::replace(qsizetype index, QBarSet *set)
将位于index 处的BarSet 替换为set 。原的BarSet 将被永久删除。
注意：此 函数可通过元对象系统及从 QML 中调用。参见Q_INVOKABLE 。
void QBarSeries::setBarWidth(qreal width)
将该系列的柱宽设置为width 。
注意： 这是属性barWidth 的设置 函数。
另请参阅 barWidth()。
void QBarSeries::setLabelsVisible(bool visible = true)
将条形系列中标签的可见性设置为visible 。
注意： 这是属性labelsVisible 的设置 函数。
另请参阅 labelsVisible()。
[signal] void QBarSeries::setValueAdded(qsizetype index, qsizetype count, QBarSet *barset)
当条形集的值发生变化时，会触发此信号。index 是该条形集在系列中的索引。新增值的数量由count 表示。barset 是指向已更改条形集的指针。
[signal] void QBarSeries::setValueChanged(qsizetype index, QBarSet *barset)
当条形集（barset）的值发生变化时，会触发此信号。index 是该条形集在系列中的索引。barset 是指向发生变化的条形集的指针。
[signal] void QBarSeries::setValueRemoved(qsizetype index, qsizetype count, QBarSet *barset)
当条形集的值发生变化时，会触发此信号。index 是该条形集在系列中的索引。被移除的值的数量由count 指示。barset 是指向已更改集合的指针。
[invokable] bool QBarSeries::take(QBarSet *set)
从系列中获取单个set 。不会删除条形集对象。
注意：该系列 仍为小节集的父对象。您必须将父对象设置为完全拥有者。
如果获取操作成功，则返回 `true `。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
[override virtual] QAbstractSeries::SeriesType QBarSeries::type() const
重新实现了属性QAbstractSeries::type 的访问函数。
返回柱状图系列。
[signal] void QBarSeries::updatedBars()
当柱状图更新时，会发出此信号。
© 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.
