Back to Qt.io
Contact Us Blog Download Qt
本页内容

QCanvasGradient Class

QCanvasGradient 是所有QCanvasPainter 渐变画笔的基类。更多内容...

标题： #include <QCanvasGradient>
CMake： find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)
target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)
自： Qt 6.11
由以下版本继承：

QCanvasBoxGradient、QCanvasConicalGradient 、QCanvasLinearGradient ，以及QCanvasRadialGradient

公共函数

QCanvasGradient()
(since 6.12) void addColorStop(qreal position, QColor color)
QColor endColor() const
void setColorAt(qreal position, QColor color)
void setEndColor(QColor color)
(since 6.12) void setImage(const QCanvasImage &image, int index = 0)
void setStartColor(QColor color)
void setStops(const QCanvasGradientStops &stops)
QColor startColor() const
QCanvasGradientStops stops() const
QCanvasBrush::BrushType type() const
operator QCanvasBrush() const &
operator QVariant() const

受保护函数

QCanvasGradient(const QCanvasGradient &)
QCanvasGradient(QCanvasGradient &&)
~QCanvasGradient()
QCanvasGradient &operator=(QCanvasGradient &&)
QCanvasGradient &operator=(const QCanvasGradient &)
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 提供任何色阶，则渐变将渲染为透明黑色（0,0,0,0）。如果仅提供一个色阶，则渐变将填充该颜色。

QCanvasPainter 在绘制渐变时采用两种不同的方法。

  • 当渐变点数量不超过 2 个时，颜色将作为 2 个 vec4 统一变量传递给着色器。这使得 2 点渐变的动画渲染性能极佳，且无需额外的中间步骤。
  • 当色阶数超过 2 个时，颜色将作为一维纹理传递给着色器。默认情况下，纹理尺寸为 1x256 像素，该设置在画质和性能方面均经过优化。 纹理会被缓存，因此当渐变停点或颜色保持不变时，即使其他渐变属性（如位置、角度等）发生变化，也可以复用之前的纹理。尽管多停点渐变的动画渲染速度很快，但会引发纹理上传操作，因此请权衡其价值。

有几个环境变量可用于控制渐变纹理的使用：

  • QCPAINTER_DISABLE_TEXTURE_USAGE_TRACKING - 默认情况下，系统会跟踪渐变纹理的使用情况并确保其数量不超过上限。设置此环境变量可禁用跟踪功能，并将所有渐变纹理保存在内存中。
  • QCPAINTER_MAX_TEXTURES - 默认情况下，纹理的最大数量为1024 。设置此环境变量以指定所需的最大纹理数量。当达到最大数量时，当前未使用的临时渐变纹理将被自动移除。

    注意： 当已禁用纹理使用情况跟踪时，此设置 无效。

成员函数文档

[delete] QCanvasGradient::QCanvasGradient()

默认构造一个QCanvasGradient 的实例。该函数已被删除。

[constexpr noexcept protected default] QCanvasGradient::QCanvasGradient(const QCanvasGradient &)

复制并构造一个QCanvasGradient 的实例。

[constexpr noexcept protected default] QCanvasGradient::QCanvasGradient(QCanvasGradient &&)

通过“Move”操作构造一个QCanvasGradient 实例。

[constexpr noexcept protected default] QCanvasGradient::~QCanvasGradient()

销毁QCanvasGradient 的实例。

[since 6.12] void QCanvasGradient::addColorStop(qreal position, QColor color)

在给定的position 上，使用给定的color 创建一个停点。给定的position 必须在0到1之间。

提供此方法是为了兼容 HTMLCanvasGradient 。它等同于setColorAt()。

该函数在 Qt 6.12 中引入。

另请参阅 setStops() 和stops()。

QColor QCanvasGradient::endColor() const

返回渐变的起始颜色或最大位置处的颜色。如果未设置任何色标，则返回透明黑色（0, 0, 0, 0）。

另请参阅 setEndColor()。

void QCanvasGradient::setColorAt(qreal position, QColor color)

在给定的position 上，使用给定的color 创建一个停点。给定的position 必须在0到1之间。

另请参阅 setStops() 和stops()。

void QCanvasGradient::setEndColor(QColor color)

将渐变的结束颜色设置为color 。这相当于调用setColorAt()，并将position参数设为1 。

另请参阅 endColor()。

[since 6.12] void QCanvasGradient::setImage(const QCanvasImage &image, int index = 0)

将image 作为y坐标为index 处的渐变源。这是设置渐变停点的另一种方法，例如使用setStops()或setColorAt()。 图像的预期默认宽度为 256 像素，但可以通过定义 QCPAINTER_GRADIENT_SIZE 进行调整。索引参数是可选的，当图像高度为 1 像素时不需要该参数。索引的最大值应为图像高度减 1。

选择使用此方法而非设置色阶的可能原因：

  • 创建速度略快，因为无需解析色阶点。此外，可通过 `index` 在单张图像中包含多个渐变。
  • 能够直接使用设计/图像中的渐变，而无需将其转换为一组色阶。
  • 支持非线性渐变，例如高斯曲线。

注意：如果 同时设置了色阶和图像，则优先使用色阶。

以下是一个关于如何使用256x1 渐变图像的简单示例：

一条从蓝色渐变为红色再变为橙色的细长水平条纹
一个正方形，其内部呈放射状渐变，从白色的中心向外过渡到红紫色的边缘
static QImage image(":/gradient1.png");
QCanvasImage gradImage = p->addImage(image);
QRectF rect(0, 0, 200, 200);
QCanvasRadialGradient rg(rect.center(), 20, 150);
rg.setImage(gradImage);
p->setFillStyle(rg);
p->fillRect(rect);

该函数在 Qt 6.12 中引入。

另请参阅 setStops()。

void QCanvasGradient::setStartColor(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

返回渐变的起始颜色或最小位置处的颜色。如果未设置任何渐变点，则返回透明黑色（0, 0, 0, 0）。

另请参阅 setStartColor()。

QCanvasGradientStops QCanvasGradient::stops() const

返回该渐变的停点。

另请参阅 setStops() 和setColorAt()。

QCanvasBrush::BrushType QCanvasGradient::type() const

返回渐变的类型。

QCanvasGradient::operator QCanvasBrush() const &

将渐变作为QCanvasBrush 返回。

该函数重载了 QCanvasGradient::operator QCanvasBrush() &&。

QCanvasGradient::operator QVariant() const

将梯度作为QVariant 返回。

[constexpr noexcept protected default] QCanvasGradient &QCanvasGradient::operator=(QCanvasGradient &&)

将other 通过“move-assign”操作赋值给此QCanvasGradient 实例。

[constexpr noexcept protected default] QCanvasGradient &QCanvasGradient::operator=(const QCanvasGradient &)

将other 复制并赋值给此QCanvasGradient 实例。

相关的非成员

QCanvasGradientStops

QList 的typedef定义 <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.