QBarSeries Class
QBarSeries 类以条形图显示数据。更多
| Header： | #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 C++ Classes for 2D 的一部分。
公共类型
| 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 | 条形图颜色 | 条形图的填充颜色。该值来自QGraphsTheme ，如果QBarSet 覆盖了颜色，则来自QBarSet::color 。 |
| QColor | 条形边框颜色 | 条形图的边框颜色。该值来自QGraphsTheme 或QBarSet::borderColor （如果QBarSet 重载了该颜色）。 |
| qreal | 条形边框宽度 | 条形图边框的宽度。该值来自QGraphsTheme 或QBarSet::borderWidth （如果QBarSet 重载了宽度）。 |
| qreal | 条形值 | 条形图的值。该值来自QBarSet::values 。 |
| QString | 条形标签 | 条形图的标签。该值来自QBarSet::label 。 |
| bool | 条形选中 | 当条形图被选中时，此值为 true，即条形图索引在QBarSet::selectedBars 中。 |
| int | barIndex | 条形图的索引，从 0 到条形图的数量 - 1。 |
要使用这些属性，请在自定义组件中添加定义名称的属性。例如"property color barColor" 和"property real barValue" 。
访问功能：
| QQmlComponent * | barDelegate() const |
| void | setBarDelegate(QQmlComponent *newBarDelegate) |
通知信号：
| void | barDelegateChanged() |
[read-only] barSets : QList<QBarSet *> const
该属性包含已添加到系列中的集合列表。
访问功能：
| QList<QBarSet *> | barSets() const |
通知信号：
| void | barSetsChanged() |
barWidth : qreal
此属性表示系列条形图的宽度。
宽度的单位是 x 轴的单位。条形图的最小宽度为零，负值视为零。将宽度设置为零意味着无论 x 轴的比例如何，屏幕上的条形图宽度都是一个像素。宽度大于零的条形图将使用 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 : const 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) |
Notifier 信号：
| void | labelsPositionChanged(QBarSeries::LabelsPosition position) |
另请参阅 labelsVisible 和labelsFormat 。
labelsPrecision : int
该属性用于保存数值标签中显示的最大有效位数。
默认值为 6。
访问功能：
| int | labelsPrecision() const |
| void | setLabelsPrecision(int precision) |
通知信号：
| void | labelsPrecisionChanged(int precision) |
labelsVisible : bool
该属性用于设置条形图系列中标签的可见性。默认标签可见性为false 。
访问功能：
| bool | labelsVisible() const |
| void | setLabelsVisible(bool visible = true) |
通知信号：
| void | labelsVisibleChanged(bool visible) |
seriesColors : QList<QColor>
该属性包含用于系列中所有对象的基色列表。
如果系列比颜色多，则颜色列表会从列表中的第一种颜色重新开始。如果未设置此属性（默认），则将使用QGraphsTheme::seriesColors 中的颜色。
访问功能
| QList<QColor> | seriesColors() const |
| void | setSeriesColors(const QList<QColor> &newSeriesColors) |
Notifier 信号：
| 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 。如果其中任何数据集为空或之前已添加到系列中，则不会添加任何数据集，函数返回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 指定的条形集添加到系列中时，将发出该信号。
[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 。
注： 属性计数的获取函数。
[invokable] qsizetype QBarSeries::find(QBarSet *set) const
根据set 的定义，返回找到的第一个BarSet 的索引。如果未找到BarSet ，则返回-1。
注： 可通过元对象系统和 QML 调用此函数。请参见Q_INVOKABLE 。
[invokable] bool QBarSeries::insert(qsizetype index, QBarSet *set)
在index 指定的位置将set 指定的条形图集插入系列，并获得该图集的所有权。如果数据集为空或已属于序列，则不会被添加。如果插入成功，则返回true 。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
bool QBarSeries::labelsVisible() const
返回标签的可见性。
注： 属性 labelsVisible 的获取函数。
另请参阅 setLabelsVisible().
[signal] void QBarSeries::labelsVisibleChanged(bool visible)
当标签的可见性更改为visible 时，将发出该信号。
注： 属性labelsVisible 的通知信号。
另请参阅 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 的数列中删除多个 BarSets。BarSets 将被永久删除。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
[invokable] bool QBarSeries::replace(const QList<QBarSet *> &sets)
用sets 指定的 BarSets 替换BarSeries 中的整个BarSet 列表。所有原始 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)
用set 替换index 中的BarSet 。原来的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)
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()
条形图更新时发出该信号。
© 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.
