Canvas QML Type

提供了一个 2D 画布组件，支持通过 JavaScript 进行绘图。更多内容...

• 所有成员列表，包括继承的成员
• 已弃用的成员

属性

• available : bool
• canvasSize : size
• context : object
• contextType : string
• renderStrategy : enumeration
• renderTarget : enumeration

信号

• imageLoaded()
• paint(rect region)
• painted()

方法

• void cancelRequestAnimationFrame(int handle)
• Context2D getContext(string contextId, ... args)
• bool isImageError(url image)
• bool isImageLoaded(url image)
• bool isImageLoading(url image)
• void loadImage(url image, size sourceSize)
• void markDirty(rect area)
• int requestAnimationFrame(callback)
• void requestPaint()
• bool save(string filename, size imageSize)
• string toDataURL(string mimeType)
• void unloadImage(url image)

详细说明

Canvas 组件支持绘制直线和曲线、简单及复杂的图形、图表以及引用图形图像。它还可以添加文本、颜色、阴影、渐变和图案，并执行低级像素操作。Canvas 的输出结果可以保存为图像文件，或序列化为 URL。

对 Canvas 的渲染通过 `Context2D ` 对象完成，通常由 `paint ` 信号触发。

要在 Canvas 控件中定义绘图区域，需设置width 和height 属性。例如，以下代码创建了一个 Canvas 控件，其绘图区域高度为 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 6.0 中，Canvas 控件支持一个渲染目标：Canvas.Image 。

Canvas.Image 渲染目标是一个QImage 对象。该渲染目标支持后台线程渲染，允许在不阻塞用户界面的情况下执行复杂或耗时的绘制操作。这是所有Qt Quick 后端均支持的唯一渲染目标。

默认的渲染目标是 Canvas.Image，默认的renderStrategy 是 Canvas.Immediate。

像素操作

支持所有 HTML5 2D 上下文的像素操作。为了确保更高的像素读写性能，应选择Canvas.Image 渲染目标。

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

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

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

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

另请参阅 Context2D 、QQuickPaintedItem 以及Qt Quick 示例——指针处理程序。

属性文档

available : bool [read-only]

表示 Canvas 何时能够提供一个可用于操作的绘图上下文。

canvasSize : size

存储上下文进行绘制的逻辑画布尺寸。

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

通过设置 canvasSize、tileSize 和 canvasWindow，Canvas 项可作为包含多个独立渲染的图块矩形的大型虚拟画布。Canvas 渲染引擎仅会渲染位于当前画布窗口内的图块。

另请参阅 tileSize 和canvasWindow 。

context : object [read-only]

保存活动绘图上下文。

如果画布已就绪，且已成功调用getContext()，或者contextType 属性已被设置为受支持的上下文类型，则该属性将包含当前的绘制上下文；否则为null。

contextType : string

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

此属性设置为当前活动上下文类型的名称。

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

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

另请参阅 getContext() 和available 。

renderStrategy : enumeration

保存当前的画布渲染策略。

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

配置或运行时测试可能会导致 QML 场景图在 GUI 线程中渲染。选择 `Canvas.Cooperative` 并不能保证渲染一定发生在与 GUI 线程分离的线程上。

默认值为Canvas.Immediate 。

另请参阅 ` renderTarget`。

renderTarget : enumeration

保存当前的画布渲染目标。

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

默认的渲染目标是Canvas.Image 。

Signal 文档

imageLoaded()

当图像加载完成时，会触发此信号。

另请参阅 loadImage()。

paint(rect region)

当需要渲染region 时，会发出此信号。如果存在活动上下文，则可通过context属性引用该上下文。

该信号可由 `markDirty()`、`requestPaint()` 或更改当前画布窗口触发。

painted()

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

方法文档

void cancelRequestAnimationFrame(int handle)

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

Context2D getContext(string contextId, ... args)

返回一个绘图上下文；如果没有可用上下文，则返回null 。

contextId 参数用于指定所需的上下文。Canvas 项将返回一个实现了所需绘制模式的上下文。首次调用 getContext 之后，后续任何使用相同 contextId 调用的 getContext 都将返回相同的上下文对象。任何其他参数（args ）目前均被忽略。

如果上下文类型不受支持，或者之前曾请求画布提供另一种不兼容的上下文类型，则会返回null 。

Canvas 仅支持 2D 上下文。

bool isImageError(url image)

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

另请参阅 loadImage()。

bool isImageLoaded(url image)

如果成功加载了image 且已准备就绪，则返回true 。

另请参阅 loadImage()。

bool isImageLoading(url image)

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

另请参阅 loadImage()。

void loadImage(url image, size sourceSize = undefined)

异步加载给定的image 。

一旦图像准备就绪，将触发imageLoaded()信号。可通过unloadImage()方法卸载已加载的图像。

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

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

void markDirty(rect area)

将指定的area 标记为“已修改”，以便当该区域可见时，画布渲染器会重新绘制它。这将触发paint 信号。

另请参阅 paint 和requestPaint()。

int requestAnimationFrame(callback)

该函数将callback 的调用安排在构建Qt Quick 场景之前执行。

void requestPaint()

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

另请参阅 markDirty()。

bool save(string filename, size imageSize = undefined)

将当前画布内容保存为图像文件filename 。保存的图像格式由filename 的后缀自动决定。成功时返回true 。如果指定了imageSize ，生成的图像将具有该尺寸，且devicePixelRatio为1.0 。否则，将应用显示该画布的窗口的devicePixelRatio()属性来处理保存的图像。

另请参阅 canvasWindow 、canvasSize 以及toDataURL()。

string toDataURL(string mimeType)

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

mimeType 的默认值为“image/png”。

另请参阅 save()。

void unloadImage(url image)

卸载image 。

一旦图像被卸载，除非再次加载，否则无法通过画布上下文进行绘制。

另请参阅 loadImage()、imageLoaded()、isImageLoaded()、Context2D::createImageData() 以及Context2D::drawImage 。