QPieSlice Class
QPieSlice 类表示饼图系列中的单个扇区。更多...
| 头文件： | #include <QPieSlice> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Graphs) target_link_libraries(mytarget PRIVATE Qt6::Graphs) |
| qmake： | QT += graphs |
| 在 QML 中： | PieSlice |
| 继承自： | QObject |
- 所有成员列表（包括继承的成员）
- QPieSlice 属于Qt Graphs 的2D C++ 类库。
公共类型
| enum class | LabelPosition { Outside, InsideHorizontal, InsideTangential, InsideNormal } |
属性
|
|
公共函数
| QPieSlice(QObject *parent = nullptr) | |
| QPieSlice(const QString &label, qreal value, QObject *parent = nullptr) | |
| virtual | ~QPieSlice() override |
| qreal | angleSpan() const |
| bool | append(QPieSlice *slice) |
| bool | append(const QList<QPieSlice *> &slices) |
| QPieSlice * | append(const QString &label, qreal value) |
| QPieSlice * | at(qsizetype index) const |
| QColor | borderColor() const |
| qreal | borderWidth() const |
| QColor | color() const |
| qreal | explodeDistanceFactor() const |
| QPieSlice * | find(const QString &label) const |
| bool | insert(qsizetype index, QPieSlice *slice) |
| bool | isEmpty() const |
| bool | isExploded() const |
| bool | isLabelVisible() const |
| QString | label() const |
| qreal | labelArmLengthFactor() const |
| QColor | labelColor() const |
| QFont | labelFont() const |
| QPieSlice::LabelPosition | labelPosition() |
| qreal | percentage() const |
| bool | remove(QPieSlice *slice) |
| bool | remove(qsizetype index) |
| void | removeMultiple(qsizetype index, int count) |
| bool | replace(QPieSlice *oldSlice, QPieSlice *newSlice) |
| bool | replace(qsizetype index, QPieSlice *slice) |
| bool | replaceAll(const QList<QPieSlice *> &slices) |
| QPieSeries * | series() const |
| void | setBorderColor(QColor color) |
| void | setBorderWidth(qreal borderWidth) |
| void | setColor(QColor color) |
| void | setExplodeDistanceFactor(qreal factor) |
| void | setExploded(bool exploded) |
| void | setLabel(const QString &label) |
| void | setLabelArmLengthFactor(qreal factor) |
| void | setLabelColor(QColor color) |
| void | setLabelFont(const QFont &font) |
| void | setLabelPosition(QPieSlice::LabelPosition position) |
| void | setLabelVisible(bool visible = true) |
| void | setSubSlicesRatio(qreal subSlicesRatio) |
| void | setValue(qreal value) |
| QQmlListProperty<QPieSlice> | sliceChildren() |
| qreal | startAngle() const |
| QList<QPieSlice *> | subSlices() const |
| qsizetype | subSlicesCount() const |
| qreal | subSlicesRatio() const |
| qreal | subSlicesSum() const |
| bool | take(QPieSlice *slice) |
| qreal | value() const |
公共槽位
| void | clear() |
信号
| void | angleSpanChanged() |
| void | borderColorChanged() |
| void | borderWidthChanged() |
| void | colorChanged() |
| void | explodeDistanceFactorChanged() |
| void | explodedChanged() |
| void | labelArmLengthFactorChanged() |
| void | labelChanged() |
| void | labelColorChanged() |
| void | labelFontChanged() |
| void | labelPositionChanged() |
| void | labelVisibleChanged() |
| void | percentageChanged() |
| void | startAngleChanged() |
| void | subSlicesAdded(const QList<QPieSlice *> &slices) |
| void | subSlicesCountChanged(qsizetype count) |
| void | subSlicesRatioChanged(qreal newSubSlicesRatio) |
| void | subSlicesRemoved(const QList<QPieSlice *> &slices) |
| void | subSlicesSumChanged(qreal sum) |
| void | valueChanged() |
详细说明
一个扇区具有一个值和一个标签。当该扇区被添加到一个饼图系列中时，QPieSeries 对象会计算该扇区相对于该系列中所有扇区总和的百分比，从而确定该扇区在图表中的实际大小。
默认情况下，标签是隐藏的。如果显示标签，则可以将其置于扇区外部并通过一条连线与扇区连接，或者将其水平居中置于扇区内部，或与扇区弧线的切线或法线平行。
默认情况下，扇区的视觉外观由主题决定，但可以通过指定扇区属性来覆盖该主题。不过，如果在自定义扇区后更改了主题，所有自定义设置都将丢失。
为了支持用户与饼图的交互，当用户点击饼图扇区或将鼠标悬停在其上时，会触发一些基本信号。
一个扇区可以包含子扇区。
另请参阅 QPieSeries 。
成员类型文档
enum class QPieSlice::LabelPosition
此枚举描述了切片标签的位置。
| 常量 | 值 | 描述 |
|---|---|---|
QPieSlice::LabelPosition::Outside | 0 | 标签位于通过一条支臂与其相连的切片之外。这是默认值。 |
QPieSlice::LabelPosition::InsideHorizontal | 1 | 标签位于切片中心，并水平排列。 |
QPieSlice::LabelPosition::InsideTangential | 2 | 标签位于切片内部居中，并旋转至与切片弧线的切线平行。 |
QPieSlice::LabelPosition::InsideNormal | 3 | 标签位于切片中心，并旋转至与切片弧的法线平行。 |
属性文档
[read-only] angleSpan : qreal
该属性存储切片的角范围（单位为度）。一个完整的圆为360度，其中0度位于12点钟方向。切片添加到系列后，该属性会自动更新。
访问函数：
| qreal | angleSpan() const |
通知信号：
| void | angleSpanChanged() |
borderColor : QColor
该属性存储用于绘制切片边框的颜色。这是一个用于修改切片的便捷属性。
访问函数：
| QColor | borderColor() const |
| void | setBorderColor(QColor color) |
通知信号：
| void | borderColorChanged() |
另请参阅 borderWidth 。
borderWidth : qreal
该属性用于设置切片边框的宽度。这是一个用于修改切片边框宽度的便捷属性。
访问函数：
| qreal | borderWidth() const |
| void | setBorderWidth(qreal borderWidth) |
通知信号：
| void | borderWidthChanged() |
另请参阅 borderColor 。
color : QColor
该属性用于存储切片的填充颜色。这是一个用于修改切片填充颜色的便捷属性。
访问函数：
| QColor | color() const |
| void | setColor(QColor color) |
通知器信号：
| void | colorChanged() |
explodeDistanceFactor : qreal
确定切片从整个饼图中向外扩展的距离。
- 1.0 表示该距离等于半径。
- 0.5 表示该距离为半径的一半。
默认距离为 0.15
访问函数：
| qreal | explodeDistanceFactor() const |
| void | setExplodeDistanceFactor(qreal factor) |
通知信号：
| void | explodeDistanceFactorChanged() |
另请参阅 exploded 。
exploded : bool
该属性表示该切片是否已从整个饼图中分离出来。
访问函数：
| bool | isExploded() const |
| void | setExploded(bool exploded) |
通知信号：
| void | explodedChanged() |
另请参阅 explodeDistanceFactor 。
label : QString
该属性存储切片的标签。
注意：该 字符串可以使用 HTML 格式。
访问函数：
| QString | label() const |
| void | setLabel(const QString &label) |
通知信号：
| void | labelChanged() |
另请参阅 labelVisible 、labelFont 以及labelArmLengthFactor 。
labelArmLengthFactor : qreal
该属性存储标签臂的长度。该数值是相对于饼图半径的倍数。例如：
- 1.0 表示该长度等于半径。
- 0.5 表示该长度为半径的一半。
默认情况下，扇区长度为 0.15
访问函数：
| qreal | labelArmLengthFactor() const |
| void | setLabelArmLengthFactor(qreal factor) |
通知信号：
| void | labelArmLengthFactorChanged() |
另请参阅 label 、labelVisible 以及labelFont 。
labelColor : QColor
此属性用于指定绘制切片标签所使用的颜色。
访问函数：
| QColor | labelColor() const |
| void | setLabelColor(QColor color) |
通知信号：
| void | labelColorChanged() |
labelFont : QFont
该属性存储用于绘制标签文本的字体。
访问函数：
| QFont | labelFont() const |
| void | setLabelFont(const QFont &font) |
通知信号：
| void | labelFontChanged() |
另请参阅 label 、labelVisible 和labelArmLengthFactor 。
labelPosition : LabelPosition
该属性用于指定切片标签的位置。
访问函数：
| QPieSlice::LabelPosition | labelPosition() |
| void | setLabelPosition(QPieSlice::LabelPosition position) |
通知信号：
| void | labelPositionChanged() |
另请参阅 label 和labelVisible 。
labelVisible : bool
该属性控制切片标签的可见性。默认情况下，该标签不可见。
访问函数：
| bool | isLabelVisible() const |
| void | setLabelVisible(bool visible = true) |
通知信号：
| void | labelVisibleChanged() |
另请参阅 label 、labelFont 以及labelArmLengthFactor 。
[read-only] percentage : qreal
该属性表示该扇区占该系列中所有扇区总和的百分比。实际值范围为 0.0 到 1.0。当该扇区被添加到系列后，该值会自动更新。
访问函数：
| qreal | percentage() const |
通知信号：
| void | percentageChanged() |
另请参阅 value 和QPieSeries::sum 。
[read-only] sliceChildren : QQmlListProperty<QPieSlice>
该切片中包含的子切片列表。这是一个默认属性，允许在 QML 的切片元素中指定子切片，而无需显式使用 children 属性名。
访问函数：
| QQmlListProperty<QPieSlice> | sliceChildren() |
[read-only] startAngle : qreal
该属性存储了该扇区在其所属系列中的起始角度。一个完整的圆为360度，其中0度位于12点钟方向。当扇区被添加到系列后，该属性会自动更新。
访问函数：
| qreal | startAngle() const |
通知信号：
| void | startAngleChanged() |
[read-only] subSlicesCount : qsizetype
该属性保存切片中的子切片数量。
访问函数：
| qsizetype | subSlicesCount() const |
通知信号：
| void | subSlicesCountChanged(qsizetype count) |
subSlicesRatio : qreal
子切片相对于父切片的相对大小。该值范围为 0.0 到 1.0，其中 1.0 表示子切片占用的空间与父切片在没有子切片时所占用的空间相同。默认值为 0.6。
访问函数：
| qreal | subSlicesRatio() const |
| void | setSubSlicesRatio(qreal subSlicesRatio) |
通知信号：
| void | subSlicesRatioChanged(qreal newSubSlicesRatio) |
[read-only] subSlicesSum : qreal
该属性存储所有子切片的总和。
该切片会记录其所包含的所有子切片的总和。
访问函数：
| qreal | subSlicesSum() const |
通知信号：
| void | subSlicesSumChanged(qreal sum) |
value : qreal
该属性保存切片值。
注意： 负值将转换为正值。
访问函数：
| qreal | value() const |
| void | setValue(qreal value) |
通知信号：
| void | valueChanged() |
另请参阅 percentage() 和QPieSeries::sum()。
成员函数文档
[explicit] QPieSlice::QPieSlice(QObject *parent = nullptr)
使用父parent 构建一个空切片。
另请参阅 QPieSeries::append() 和QPieSeries::insert()。
QPieSlice::QPieSlice(const QString &label, qreal value, QObject *parent = nullptr)
根据指定的value 、label 和parent 构建一个空切片。
另请参阅 QPieSeries::append() 和QPieSeries::insert()。
[override virtual noexcept] QPieSlice::~QPieSlice()
删除该切片。如果该切片已添加到系列中，则不应将其删除。
[invokable] bool QPieSlice::append(QPieSlice *slice)
将由 `slice ` 指定的子切片追加到该切片中。子切片的所有权将转移给该切片。
若追加成功，则返回 `true `。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] bool QPieSlice::append(const QList<QPieSlice *> &slices)
将由 `slices ` 指定的子切片数组追加到该切片中。子切片的所有权将转移给该切片。
若追加成功，则返回 `true `。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] QPieSlice *QPieSlice::append(const QString &label, qreal value)
将一个具有指定value 和label 的子切片追加到切片中。子切片的所有权将传递给该切片。如果value 的值为NaN 、Inf 或-Inf ，则返回null，且不会向序列中添加任何内容。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] QPieSlice *QPieSlice::at(qsizetype index) const
返回位于位置index 处的PieSlice 。若未找到PieSlice ，则返回 null。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[slot] void QPieSlice::clear()
清除该切片中的所有子切片。
[invokable] QPieSlice *QPieSlice::find(const QString &label) const
搜索包含标签label 的PieSlice 。若找到，则返回PieSlice ；否则返回 null。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] bool QPieSlice::insert(qsizetype index, QPieSlice *slice)
将由 `slice ` 指定的子切片插入到该子切片之前、位于 `index` 指定位置处的切片中。子切片的所有权将传递给该切片。
若插入成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
bool QPieSlice::isEmpty() const
如果子切片列表为空，则返回true 。
[invokable] bool QPieSlice::remove(QPieSlice *slice)
从切片中移除由 `slice` 指定的单个子切片，并将其永久删除。
调用此函数后，该指针将无法被引用。
如果删除成功，则返回true 。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] bool QPieSlice::remove(qsizetype index)
删除位于index 位置的PieSlice 。该PieSlice 将被永久删除。若删除成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QPieSlice::removeMultiple(qsizetype index, int count)
从index 开始，移除count 个PieSlice。这些PieSlice将被永久删除。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] bool QPieSlice::replace(QPieSlice *oldSlice, QPieSlice *newSlice)
如果在切片中找到PieSlice oldSlice ，则将其替换为newSlice 。oldSlice 将被永久删除。如果替换成功，则返回true 。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
[invokable] bool QPieSlice::replace(qsizetype index, QPieSlice *slice)
将位置为index 的PieSlice 替换为slice 指定的内容。原始的PieSlice 将被永久删除。如果替换任何一个 PieSlices 失败，则返回false 。
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
[invokable] bool QPieSlice::replaceAll(const QList<QPieSlice *> &slices)
将该扇区中的所有 PieSlices 替换为由 `slices` 指定的列表。所有原始的 PieSlices 将被永久删除。如果所有 PieSlices 均成功替换，则返回 `true `。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
QPieSeries *QPieSlice::series() const
返回该切片所属的序列。
另请参阅 QPieSeries::append()。
QList<QPieSlice *> QPieSlice::subSlices() const
返回属于该切片的子切片列表。
[signal] void QPieSlice::subSlicesAdded(const QList<QPieSlice *> &slices)
当将由slices 指定的子切片添加到切片中时，会发出此信号。
另请参阅 append()。
qsizetype QPieSlice::subSlicesCount() const
返回该切片中子切片的数量。
注意： 这是属性 subSlicesCount 的获取 函数。
[signal] void QPieSlice::subSlicesRemoved(const QList<QPieSlice *> &slices)
当由slices 指定的子切片从切片中移除时，会发出此信号。
另请参阅 remove()。
qreal QPieSlice::subSlicesSum() const
返回该切片中所有子切片值的总和。
注意： 这是属性 subSlicesSum 的获取 函数。
另请参阅 QPieSlice::value()、QPieSlice::setValue() 和QPieSlice::percentage()。
[invokable] bool QPieSlice::take(QPieSlice *slice)
从序列中获取一个由 `slice` 指定的子切片。不会删除该切片对象。
注意：该 切片仍保留其父对象。您必须设置父对象以获得完全所有权。
如果提取操作成功，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
© 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.
