Back to Qt.io
Contact Us Blog Download Qt

Canvas QML Type

提供一个 2D 画布项，可通过 JavaScript 进行绘图。更多

Import Statement: import QtQuick
Inherits:

Item

属性

信号

方法

详细说明

画布项允许绘制直线和曲线、简单和复杂的形状、图形以及引用的图形图像。它还可以添加文本、颜色、阴影、渐变和图案，并进行低级像素操作。画布输出可保存为图像文件或序列化为 URL。

向画布渲染是通过Context2D 对象完成的，通常是paint 信号的结果。

要在 Canvas 项目中定义绘图区域，请设置width 和height 属性。例如，下面的代码创建了一个画布项，其绘图区域的高度为 100 像素，宽度为 200 像素：

import QtQuick 2.0
Canvas {
    id: mycanvas
    width: 100
    height: 200
    onPaint: {
        var ctx = getContext("2d");
        ctx.fillStyle = Qt.rgba(1, 0, 0, 1);
        ctx.fillRect(0, 0, width, height);
    }
}

目前，Canvas 项目仅支持二维渲染上下文。

线程渲染和渲染目标

在 Qt XML 6.0 中，Canvas 项目支持一个呈现目标：Canvas.Image 。

Canvas.Image 渲染目标是一个QImage 对象。该呈现目标支持后台线程呈现，允许在不阻塞 UI 的情况下执行复杂或长时间运行的绘制。这是所有Qt Quick 后端都支持的唯一一个呈现目标。

默认呈现目标是 Canvas.Image，默认renderStrategy 是 Canvas.Immediate。

像素操作

支持所有 HTML5 2D 上下文像素操作。为确保提高像素读/写性能，应选择Canvas.Image 呈现目标。

移植现有 HTML5 画布应用程序的提示

尽管 Canvas 项目提供了类似 HTML5 的 API，但仍需对 HTML5 画布应用程序进行修改才能在 Canvas 项目中运行：

  • 用 QML 属性绑定或 Canvas 项目方法替换所有 DOM API 调用。
  • 使用MouseArea 项目替换所有 HTML 事件处理程序。
  • 使用Timer 项目或requestAnimationFrame() 替换 setInterval/setTimeout 函数调用。
  • 将绘制代码放入onPaint 处理程序，并通过调用markDirty() 或requestPaint() 方法触发绘制。
  • 要绘制图像，可通过调用 Canvas 的loadImage() 方法加载图像，然后在onImageLoaded 处理程序中请求绘制图像。

从 Qt 5.4 开始，画布是一个texture provider ，可以直接在ShaderEffects 和其他消耗纹理提供程序的类中使用。

注意： 一般来说，Canvas.Image 渲染目标应避免使用大画布、频繁更新和动画。这是因为使用加速图形 API 时，每次更新都会导致纹理上传。此外，如果可能的话，请首选QQuickPaintedItem ，并通过QPainter 在 C++ 中实现绘制，而不是采用成本更高、性能可能更差的 JavaScript 和Context2D 方法。

另请参阅 Context2D 、QQuickPaintedItem 和Qt Quick 示例 - 指针处理程序。

属性文档

available : bool [read-only]

表示画布何时能够提供可在其上操作的绘图上下文。


canvasSize : size

保存上下文绘制的逻辑画布尺寸。

默认情况下，画布大小与当前画布项大小相同。

通过设置 canvasSize、tileSize 和 canvasWindow，画布项可以充当一个大型虚拟画布，其中包含许多单独渲染的矩形块。画布呈现引擎只绘制当前画布窗口内的瓷砖。

另请参阅 tileSize 和canvasWindow 。


context : object [read-only]

保持活动绘图上下文。

如果画布已准备就绪，并且成功调用了getContext() 或contextType 属性已设置为受支持的上下文类型，则此属性将包含当前的绘图上下文，否则为空。


contextType : string

要使用的绘图上下文类型。

该属性将设置为活动上下文类型的名称。

如果明确设置，画布将在可用后尝试创建指定类型的上下文。

该类型名称与getContext() 调用中使用的名称相同，对于 2d 画布，该值为 "2d"。

另请参阅 getContext() 和available 。


renderStrategy : enumeration

当前画布渲染策略。

常量说明
Canvas.Immediatecontext 将在主 UI 线程中立即执行图形命令。
Canvas.Threadedcontext 将图形命令延迟到私有渲染线程。
Canvas.Cooperativecontext 将图形命令延迟到应用程序的全局渲染线程。

该提示与renderTarget 一起提供给图形上下文，以确定渲染方法。图形上下文可能不支持呈现策略（renderStrategy）、renderTarget 或其组合，在这种情况下，上下文将选择适当的选项，Canvas 将向属性发出更改信号。

配置或运行时测试可能会导致 QML 场景图在 GUI 线程中渲染。选择Canvas.Cooperative ，并不能保证在独立于 GUI 线程的线程上进行渲染。

默认值是Canvas.Immediate 。

另请参阅 renderTarget 。


renderTarget : enumeration

保持当前画布渲染目标。

常量说明
Canvas.Image渲染到内存中的图像缓冲区。
Canvas.FramebufferObject从 Qt 6.0 开始，此值将被忽略。

该提示与renderStrategy 一起提供给图形上下文，以确定渲染方法。图形上下文可能不支持renderStrategy 、renderTarget 或其组合，在这种情况下，上下文将选择适当的选项，Canvas 将向属性发出更改信号。

默认的呈现目标是Canvas.Image 。


信号文档

imageLoaded()

加载图像时会发出该信号。

注： 相应的处理程序是onImageLoaded 。

另请参阅 loadImage() 。


paint(rect region)

当region 需要渲染时，会发出该信号。如果上下文处于活动状态，则可从上下文属性中引用该上下文。

该信号可通过markDirty(),requestPaint() 或更改当前画布窗口触发。

注： 相应的处理程序是onPaint 。


painted()

该信号在所有上下文绘制命令执行完毕且画布已渲染后发出。

注： 相应的处理程序是onPainted 。


方法文档

cancelRequestAnimationFrame(int handle)

此函数将取消handle 引用的动画回调。


object getContext(string contextId, ... args)

返回绘制上下文，如果没有可用上下文，则返回null 。

contextId 参数命名所需的上下文。Canvas 项将返回一个实现所需绘图模式的上下文。在第一次调用 getContext 后，以后任何使用相同 contextId 的 getContext 调用都将返回相同的上下文对象。任何附加参数 (args) 目前都将被忽略。

如果不支持上下文类型，或者之前已请求画布提供不同且不兼容的上下文类型，则将返回null 。

画布只支持 2d 上下文。


isImageError(url image)

如果image 加载失败，则返回true ，否则返回false 。

另请参阅 loadImage() 。


isImageLoaded(url image)

如果image 已成功加载并可使用，则返回 true。

另请参阅 loadImage()。


isImageLoading(url image)

如果image 正在加载，则返回 true。

另请参阅 loadImage()。


loadImage(url image, size sourceSize = undefined)

异步加载给定的image 。

一旦图片就绪，imageLoaded() 信号就会发出。可使用unloadImage() 方法卸载已加载的图像。

注意： 只有加载的图像才能绘制到画布项目上。

如果指定了sourceSize ，图像将在加载过程中缩放至该尺寸。这对于以预期显示尺寸加载可缩放（矢量）图像（如 SVGs）非常有用。该参数在 Qt 6.7 中引入。

另请参阅 unloadImage()、imageLoaded()、isImageLoaded()、Context2D::createImageData() 和Context2D::drawImage()。


markDirty(rect area)

将给定的area 标记为脏区域，这样当该区域可见时，画布呈现器将重新绘制它。这将触发paint 信号。

另请参阅 paint 和requestPaint()。


int requestAnimationFrame(callback)

此函数安排在组成Qt Quick 场景之前调用callback 。


requestPaint()

请求重新绘制整个可见区域。

另请参阅 markDirty()。


bool save(string filename, size imageSize = undefined)

将当前画布内容保存为图像文件filename 。保存的图像格式由filename 的后缀自动决定。成功后会返回true 。如果指定了imageSize ，生成的图像将具有此大小，并且设备像素比例为1.0 。否则，画布显示窗口的devicePixelRatio() 将应用于保存的图像。

注意： 调用此方法将强制绘制整个画布，而不仅仅是当前画布的可见窗口。

另请参阅 canvasWindow 、canvasSize 和toDataURL()。


string toDataURL(string mimeType)

返回画布中图像的数据 URL。

默认mimeType 为 "image/png"。

另请参阅 save() 。


unloadImage(url image)

卸载image 。

卸载图像后，除非再次加载，否则画布上下文将无法绘制图像。

另请参阅 loadImage(),imageLoaded(),isImageLoaded(),Context2D::createImageData() 和Context2D::drawImage 。


© 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.