QPieSeries Class
QPieSeries 类用于以饼图形式展示数据。更多内容...
| 头文件： | #include <QPieSeries> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Graphs) target_link_libraries(mytarget PRIVATE Qt6::Graphs) |
| qmake： | QT += graphs |
| 在 QML 中： | PieSeries |
| 继承自： | QAbstractSeries |
- 所有成员列表（包括继承的成员）
- QPieSeries 属于Qt Graphs 的2D C++ 类。
公共类型
(since 6.10) enum class | LabelVisibility { None, First, Even, Odd } |
属性
|
|
公共函数
| QPieSeries(QObject *parent = nullptr) | |
| QPieSeries::LabelVisibility | angleSpanLabelVisibility() const |
| qreal | angleSpanVisibleLimit() const |
| bool | append(QPieSlice *slice) |
| bool | append(const QList<QPieSlice *> &slices) |
| QPieSlice * | append(const QString &label, qreal value) |
| QPieSlice * | at(qsizetype index) |
| void | clear() |
| qsizetype | count() const |
| qreal | endAngle() const |
| QPieSlice * | find(const QString &label) |
| qreal | holeSize() const |
| qreal | horizontalPosition() const |
| bool | insert(qsizetype index, QPieSlice *slice) |
| bool | isEmpty() const |
| qreal | pieSize() const |
| bool | remove(QPieSlice *slice) |
| bool | remove(qsizetype index) |
| void | removeMultiple(qsizetype index, int count) |
| bool | replace(const QList<QPieSlice *> &slices) |
| bool | replace(QPieSlice *oldSlice, QPieSlice *newSlice) |
| bool | replace(qsizetype index, QPieSlice *slice) |
| void | setAngleSpanLabelVisibility(QPieSeries::LabelVisibility newAngleSpanVisibleMode) |
| void | setAngleSpanVisibleLimit(qreal newAngleSpanVisibleLimit) |
| void | setEndAngle(qreal angle) |
| void | setHoleSize(qreal holeSize) |
| void | setHorizontalPosition(qreal relativePosition) |
| void | setLabelsPosition(QPieSlice::LabelPosition position) |
| void | setLabelsVisible(bool visible) |
| void | setPieSize(qreal relativeSize) |
| void | setSliceData(const QList<qreal> &newSliceData) |
| void | setSliceLabels(QStringList newLabels) |
| void | setStartAngle(qreal angle) |
| void | setVerticalPosition(qreal relativePosition) |
| QList<qreal> | sliceData() const |
| const QStringList & | sliceLabels() const & |
| QStringList | sliceLabels() && |
| QList<QPieSlice *> | slices() const |
| qreal | startAngle() const |
| qreal | sum() const |
| bool | take(QPieSlice *slice) |
| qreal | verticalPosition() const |
| QPieSeries & | operator<<(QPieSlice *slice) |
重新实现的公共函数
| virtual QAbstractSeries::SeriesType | type() const override |
信号
| void | added(const QList<QPieSlice *> &slices) |
| void | angleSpanLabelVisibilityChanged(QPieSeries::LabelVisibility visibility) |
| void | angleSpanVisibleLimitChanged(qreal limit) |
| void | countChanged() |
| void | endAngleChanged() |
| void | holeSizeChanged() |
| void | horizontalPositionChanged() |
| void | pieSizeChanged() |
| void | removed(const QList<QPieSlice *> &slices) |
| void | sliceDataChanged(const QList<qreal> &sliceData) |
| void | sliceLabelsChanged(const QStringList &sliceLabels) |
| void | startAngleChanged() |
| void | sumChanged() |
| void | verticalPositionChanged() |
详细说明
一个饼图系列由定义为QPieSlice 对象的扇区组成。这些扇区可以具有任意数值，因为QPieSeries对象会计算每个扇区相对于该系列中所有扇区总和的百分比，从而确定该扇区在图表中的实际大小。
饼图的大小及其在图表上的位置通过 0.0 到 1.0 之间的相对值来控制。这些值与图表的实际矩形区域相关。
默认情况下，饼图被定义为完整饼图。可以通过为系列设置起始角度和角度范围来创建部分饼图。完整饼图为 360 度，其中 0 度位于 12 点钟方向。
另请参阅 QPieSlice 。
成员类型文档
[since 6.10] enum class QPieSeries::LabelVisibility
标签可见性模式。
| 常量 | 值 | 描述 |
|---|---|---|
QPieSeries::LabelVisibility::None | 0 | 角度跨度小于angleSpanVisibleLimit 的切片的所有标签都将被隐藏。 |
QPieSeries::LabelVisibility::First | 1 | 对于角度跨度小于angleSpanVisibleLimit 的连续切片，除第一个标签外，其余所有标签都将被隐藏。这是默认值。 |
QPieSeries::LabelVisibility::Even | 2 | 从第二个开始，角度跨度小于angleSpanVisibleLimit 的连续切片中的每个隔一个标签将被隐藏。 |
QPieSeries::LabelVisibility::Odd | 3 | 对于角度跨度小于angleSpanVisibleLimit 的连续切片，将从第一个标签开始，每隔一个标签隐藏。 |
该枚举类型于 Qt 6.10 中引入。
属性文档
[since 6.10] angleSpanLabelVisibility : LabelVisibility
该属性用于控制标签的可见性模式。
该模式用于确定当标签位于通过angleSpanVisibleLimit 设置的角度范围限制内时，哪些标签将被隐藏。若未设置angleSpanVisibleLimit ，则此模式无效。
该枚举在 Qt 6.10 中引入。
访问函数：
| QPieSeries::LabelVisibility | angleSpanLabelVisibility() const |
| void | setAngleSpanLabelVisibility(QPieSeries::LabelVisibility newAngleSpanVisibleMode) |
通知器信号：
| void | angleSpanLabelVisibilityChanged(QPieSeries::LabelVisibility visibility) |
另请参阅 QPieSeries::angleSpanVisibleLimit 。
[since 6.10] angleSpanVisibleLimit : qreal
该属性用于设置标签可见性的角度范围限制。
将作为切片标签可见性限制的角度跨度。角度跨度小于此值的切片将根据系列中设置的angleSpanLabelVisibility 来改变其可见性。默认值为0 ，这意味着无论angleSpanLabelVisibility 如何设置，都不会隐藏任何切片。
该枚举类型在 Qt 6.10 中引入。
访问函数：
| qreal | angleSpanVisibleLimit() const |
| void | setAngleSpanVisibleLimit(qreal newAngleSpanVisibleLimit) |
通知器信号：
| void | angleSpanVisibleLimitChanged(qreal limit) |
另请参阅 QPieSeries::angleSpanLabelVisibility 。
[read-only] count : qsizetype
该属性存储序列中的分片数量。
访问函数：
| qsizetype | count() const |
通知信号：
| void | countChanged() |
endAngle : qreal
该属性存储了扇形的结束角度。
一个完整的扇形为360度，其中0度位于12点钟方向。
默认值为 360。
访问函数：
| qreal | endAngle() const |
| void | setEndAngle(qreal angle) |
通知信号：
| void | endAngleChanged() |
holeSize : qreal
该属性用于存储甜甜圈孔的大小。
设置pieSize 属性时，该属性会根据需要进行调整，以确保孔洞大小不超过饼图大小。
默认值为 0.0。
访问函数：
| qreal | holeSize() const |
| void | setHoleSize(qreal holeSize) |
通知信号：
| void | holeSizeChanged() |
horizontalPosition : qreal
该属性用于设置饼图的水平位置。
该值相对于图表矩形，因此：
- 0.0 表示绝对左侧。
- 1.0 表示绝对右侧。
默认值为 0.5（居中）。
访问函数：
| qreal | horizontalPosition() const |
| void | setHorizontalPosition(qreal relativePosition) |
通知信号：
| void | horizontalPositionChanged() |
另请参阅 verticalPosition 。
pieSize : qreal
该属性用于存储饼图的大小。
该值相对于图表矩形，因此：
- 0.0 表示最小 pieSize（不绘制饼图）。
- 1.0 是图表中可容纳的最大 pieSize 值。
设置此属性时，系统会根据需要调整 `holeSize ` 属性，以确保空洞大小不超过饼图大小。
默认值为 0.7。
访问函数：
| qreal | pieSize() const |
| void | setPieSize(qreal relativeSize) |
通知器信号：
| void | pieSizeChanged() |
[since 6.12] sliceData : QList<qreal>
声明式扇区值。
将此属性设置为该值可声明式地创建扇区。该系列会根据每个值自动创建一个扇区。标签可通过sliceLabels 提供。
注意： 不支持混合使用 声明式和命令式数据输入。
此枚举类型在 Qt 6.12 中引入。
访问函数：
| QList<qreal> | sliceData() const |
| void | setSliceData(const QList<qreal> &newSliceData) |
通知器信号：
| void | sliceDataChanged(const QList<qreal> &sliceData) |
另请参阅 sliceLabels 。
[since 6.12] sliceLabels : QStringList
声明式切片标签。
为通过 `sliceData` 创建的切片提供标签。标签的顺序必须与值的顺序一致。超过切片数量的额外标签将被忽略。
注意： 不支持在数据输入中混合使用 声明式和命令式表达。
此枚举类型于 Qt 6.12 中引入。
访问函数：
| const QStringList & | sliceLabels() const & |
| QStringList | sliceLabels() && |
| void | setSliceLabels(QStringList newLabels) |
通知器信号：
| void | sliceLabelsChanged(const QStringList &sliceLabels) |
另请参阅 sliceData 。
startAngle : qreal
该属性存储了扇形的起始角度。
一个完整的圆饼图为360度，其中0度位于12点钟方向。
默认值为 0。
访问函数：
| qreal | startAngle() const |
| void | setStartAngle(qreal angle) |
通知信号：
| void | startAngleChanged() |
[read-only] sum : qreal
该属性存储所有切片的总和。
该序列会记录其所包含的所有切片的总和。
访问函数：
| qreal | sum() const |
通知信号：
| void | sumChanged() |
verticalPosition : qreal
该属性控制饼图的垂直位置。
该值相对于图表矩形，因此：
- 0.0 表示绝对顶部。
- 1.0 表示绝对底部。
默认值为 0.5（居中）。
访问函数：
| qreal | verticalPosition() const |
| void | setVerticalPosition(qreal relativePosition) |
通知信号：
| void | verticalPositionChanged() |
另请参阅 horizontalPosition 。
成员函数文档
[explicit] QPieSeries::QPieSeries(QObject *parent = nullptr)
创建一个系列对象，该对象是parent 的子对象。
[signal] void QPieSeries::added(const QList<QPieSlice *> &slices)
当通过slices 指定的切片被添加到序列中时，会发出此信号。
另请参阅 append()。
[invokable] bool QPieSeries::append(QPieSlice *slice)
将由 `slice ` 指定的切片追加到序列中。切片的所有权将转移给该序列。
若追加成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] bool QPieSeries::append(const QList<QPieSlice *> &slices)
将由 `slices ` 指定的切片数组追加到序列中。切片的所有权将传递给该序列。
若追加成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
[invokable] QPieSlice *QPieSeries::append(const QString &label, qreal value)
将一个具有指定value 和label 的切片追加到序列中。切片的所有权将传递给序列。如果value 的值为NaN 、Inf 或-Inf ，则返回null，且不会向序列中添加任何内容。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
[invokable] QPieSlice *QPieSeries::at(qsizetype index)
返回位于位置index 的“PieSlice ”。如果未找到PieSlice ，则返回 null。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QPieSeries::clear()
清除该序列中的所有切片。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
qsizetype QPieSeries::count() const
返回该序列中切片的数量。
注意： 这是 count 属性的获取 函数。
qreal QPieSeries::endAngle() const
返回扇形的结束角度。
一个完整的扇形为 360 度，其中 0 度位于 12 点钟方向。
注意： 这是 endAngle 属性的获取 函数。
另请参阅 setEndAngle()、startAngle() 和setStartAngle()。
[invokable] QPieSlice *QPieSeries::find(const QString &label)
搜索包含标签label 的PieSlice 。若找到，则返回PieSlice ；否则返回 null。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
[invokable] bool QPieSeries::insert(qsizetype index, QPieSlice *slice)
将由 `slice ` 指定的切片插入到序列中，位于由 `index` 指定的位置前的切片之前。切片的所有权将传递给该序列。
若插入成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
bool QPieSeries::isEmpty() const
如果序列为空，则返回true 。
[invokable] bool QPieSeries::remove(QPieSlice *slice)
从序列中移除由 `slice` 指定的单个切片，并将其永久删除。
调用此方法后，该指针将无法被引用。
如果移除成功，则返回true 。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
[invokable] bool QPieSeries::remove(qsizetype index)
删除位于index 位置的PieSlice 。该PieSlice 将被永久删除。若删除成功，则返回true 。
注意： 可通过元对象系统和从 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QPieSeries::removeMultiple(qsizetype index, int count)
从索引index 开始，从该系列中移除数量为count 的多个PieSlices。这些PieSlices将被永久删除。
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
[signal] void QPieSeries::removed(const QList<QPieSlice *> &slices)
当由slices 指定的切片从序列中移除时，会发出此信号。
另请参阅 remove()。
[invokable] bool QPieSeries::replace(const QList<QPieSlice *> &slices)
将系列中的所有 PieSlices 替换为由 `slices` 指定的列表。所有原始的 PieSlices 都将被永久删除。如果所有 PieSlices 均被成功替换，则返回 `true `。
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
[invokable] bool QPieSeries::replace(QPieSlice *oldSlice, QPieSlice *newSlice)
如果系列中存在PieSlice oldSlice ，则将其替换为newSlice 。oldSlice 将被永久删除。如果替换成功，则返回true 。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] bool QPieSeries::replace(qsizetype index, QPieSlice *slice)
将位置为index 的PieSlice 替换为由slice 指定的对象。原始的PieSlice 将被永久删除。如果替换任何一个PieSlices失败，则返回false 。
注意：此 函数可通过元对象系统及从 QML 中调用。参见Q_INVOKABLE 。
void QPieSeries::setEndAngle(qreal angle)
设置扇形的结束角度。
一个完整的扇形为360度，其中0度位于12点钟方向。
angle 该值必须大于起始角度。
注意： 这是属性endAngle 的设置 函数。
另请参阅 endAngle()、startAngle() 和setStartAngle()。
void QPieSeries::setLabelsPosition(QPieSlice::LabelPosition position)
将所有扇区标签的位置设置为position 。
注意：此 函数仅影响该系列中的当前扇区。如果添加了新的扇区，其默认标签位置为 QPieSlice::LabelOutside。
另请参阅 QPieSlice::labelPosition() 和QPieSlice::setLabelPosition()。
void QPieSeries::setLabelsVisible(bool visible)
将所有切片标签的可见性设置为visible 。
注意：此 函数仅影响该系列中的当前切片。如果添加了新的切片，其默认标签可见性为false 。
另请参阅 QPieSlice::isLabelVisible() 和QPieSlice::setLabelVisible()。
void QPieSeries::setStartAngle(qreal angle)
设置扇形图的起始角度。
一个完整的扇形为360度，其中0度位于12点钟方向。
angle 必须小于结束角度。
注意： 这是属性startAngle 的设置 函数。
另请参阅 startAngle()、endAngle() 和setEndAngle()。
QList<QPieSlice *> QPieSeries::slices() const
返回属于该序列的切片列表。
qreal QPieSeries::startAngle() const
返回扇形的起始角度。
一个完整的饼图为360度，其中0度位于12点钟方向。
注意： 这是 startAngle 属性的获取 函数。
另请参阅 setStartAngle()、endAngle() 和setEndAngle()。
qreal QPieSeries::sum() const
返回该序列中所有切片值的总和。
注意： 这是 sum 属性的获取 函数。
另请参阅 QPieSlice::value()、QPieSlice::setValue() 和QPieSlice::percentage()。
[invokable] bool QPieSeries::take(QPieSlice *slice)
从序列中获取一个由slice 指定的切片。不会删除该切片对象。
注意：序列 仍为切片的父对象。若要获得完全所有权，必须将父对象进行设置。
如果提取操作成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[override virtual] QAbstractSeries::SeriesType QPieSeries::type() const
重新实现了属性QAbstractSeries::type 的访问函数。
返回序列的类型。
QPieSeries &QPieSeries::operator<<(QPieSlice *slice)
将由slice 指定的切片追加到序列中，并返回该序列的引用。切片的所有权将转移给该序列。
© 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.
