QCanvasGradient Class
QCanvasGradient 是所有QCanvasPainter 梯度笔刷的基类。更多
| 头文件： | #include <QCanvasGradient> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter) |
| 自 | Qt 6.11 |
| 继承 | QCanvasBrush |
| 继承于 | QCanvasBoxGradient,QCanvasConicalGradient,QCanvasLinearGradient, 和QCanvasRadialGradient |
| 状态： | 技术预览 |
公共函数
| QColor | endColor() const |
| void | setColorAt(float position, const QColor &color) |
| void | setEndColor(const QColor &color) |
| void | setStartColor(const QColor &color) |
| void | setStops(const QCanvasGradientStops &stops) |
| QColor | startColor() const |
| QCanvasGradientStops | stops() const |
| QCanvasBrush::BrushType | type() const |
| operator QVariant() const |
相关非成员
| QCanvasGradientStops | |
| bool | operator!=(const QCanvasGradient &lhs, const QCanvasGradient &rhs) |
| QDataStream & | operator<<(QDataStream &stream, const QCanvasGradient &gradient) |
| QDataStream & | operator<<(QDataStream &stream, const QCanvasGradientStop &stop) |
| bool | operator==(const QCanvasGradient &lhs, const QCanvasGradient &rhs) |
| QDataStream & | operator>>(QDataStream &stream, QCanvasGradient &gradient) |
| QDataStream & | operator>>(QDataStream &stream, QCanvasGradientStop &stop) |
详细说明
QCanvasGradient 是所有QCanvasPainter 梯度笔刷的基类。目前有四种渐变类型：QCanvasLinearGradient,QCanvasRadialGradient,QCanvasConicalGradient 和QCanvasBoxGradient 。
如果在setStartColor 、setEndColor 、setColorAt 或setStops 中没有提供止点，则渐变效果的起始颜色为白色（255,255,255），结束颜色为透明（0,0,0,0）。如果只提供了一个停止点，则会用该颜色填充渐变。
QCanvasPainter 使用两种不同的方法绘制渐变。
- 如果最多提供 2 个停止点，则颜色会以 2 个 vec4 单位的形式传入着色器。这使得 2 停点渐变的动画效果非常好，中间没有额外的步骤。
- 如果颜色超过 2 个色块，则会以一维纹理的形式传入着色器。默认情况下，纹理大小为 1x256 像素，并对质量和性能进行了优化。纹理会被缓存，因此当渐变停止或颜色不变时，即使其他渐变属性（如位置、角度等）发生变化，之前的纹理也可以重复使用。虽然多停顿渐变动画的速度很快，但会导致纹理上传，所以要考虑是否值得。
有几个环境变量可以控制渐变纹理的使用：
- QCPAINTER_DISABLE_TEXTURE_USAGE_TRACKING - 默认情况下，渐变纹理使用量会被跟踪并保持在最大值以下。设置此环境变量可禁用跟踪并将所有渐变纹理保留在内存中。
- QCPAINTER_MAX_TEXTURES - 默认情况下，纹理的最大数量为
1024。将此环境变量设置为所需的最大纹理数量。达到最大数量后，当前未使用的临时渐变纹理将自动删除。注意： 如果已禁用纹理使用跟踪功能，则不会产生影响。
成员函数文档
QColor QCanvasGradient::endColor() const
返回渐变结束颜色或最大位置的颜色。如果未设置结束颜色，则返回默认的透明黑色结束颜色（0, 0, 0, 0）。
另请参见 setEndColor().
void QCanvasGradient::setColorAt(float position, const QColor &color)
使用给定的color 在给定的position 处创建停止点。position 的范围必须在 0 到 1 之间。
void QCanvasGradient::setEndColor(const QColor &color)
将渐变的结束颜色设置为color 。这等同于调用setColorAt() 的位置1 。
另请参阅 endColor() 。
void QCanvasGradient::setStartColor(const QColor &color)
将渐变的起始颜色设置为color 。这相当于调用setColorAt() 的位置0 。
另请参阅 startColor() 。
void QCanvasGradient::setStops(const QCanvasGradientStops &stops)
用给定的stops 替换当前的停止点集合。
停止点列表的规则如下：
- 列表应至少包含 2 个止损点。
- 止损点的位置必须在 0 到 1 的范围内，并且必须以最低的止损点为优先排序。
- 第一个位置必须是 0.0，最后一个位置必须是 1.0。
另请参阅 setColorAt() 和stops()。
QColor QCanvasGradient::startColor() const
返回渐变起始颜色或最小位置的颜色。如果未设置起始颜色，则返回默认起始颜色白色（255, 255, 255）。
另请参见 setStartColor().
QCanvasGradientStops QCanvasGradient::stops() const
返回该梯度的停止点。
另请参阅 setStops() 和setColorAt()。
QCanvasBrush::BrushType QCanvasGradient::type() const
返回梯度类型。
QCanvasGradient::operator QVariant() const
以QVariant 的形式返回梯度。
相关非会员
QCanvasGradientStops
QList<QCanvasGradientStop> 的类型定义。
[noexcept] bool operator!=(const QCanvasGradient &lhs, const QCanvasGradient &rhs)
如果梯度lhs 与rhs 不同，则返回true ；否则返回false 。
另请参见 operator==().
QDataStream &operator<<(QDataStream &stream, const QCanvasGradient &gradient)
将给定的gradient 写入给定的stream ，并返回对stream 的引用。
另请参阅 序列化 Qt 数据类型。
QDataStream &operator<<(QDataStream &stream, const QCanvasGradientStop &stop)
将梯度stop 写入给定的stream ，并返回对stream 的引用。
另请参阅 序列化 Qt 数据类型。
[noexcept] bool operator==(const QCanvasGradient &lhs, const QCanvasGradient &rhs)
如果梯度lhs 等于rhs ，则返回true ；否则返回false 。
另请参见 operator!=().
QDataStream &operator>>(QDataStream &stream, QCanvasGradient &gradient)
从给定的stream 中读取给定的gradient ，并返回对stream 的引用。
另请参阅 序列化 Qt 数据类型。
QDataStream &operator>>(QDataStream &stream, QCanvasGradientStop &stop)
从给定的stream 中读取梯度stop ，并返回对stream 的引用。
另请参阅 序列化 Qt 数据类型。
© 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.
