En esta página

Canvas2D QML Type

Ofrece un elemento de lienzo 2D que permite dibujar mediante JavaScript. Más información...

Import Statement: import QtCanvas2D
Since: Qt 6.12
Status: Technology preview

Este tipo se encuentra en fase de vista previa tecnológica y está sujeto a cambios.

Propiedades

Señales

Métodos

Descripción detallada

El elemento Canvas2D permite dibujar líneas rectas y curvas, formas simples y complejas, gráficos e imágenes gráficas referenciadas. También permite añadir texto, colores, degradados y patrones.

El renderizado en el Canvas se realiza mediante un objeto ` Canvas2DContext `, normalmente como resultado de la señal ` paint `.

Para definir un área de dibujo en el elemento Canvas2D, configura las propiedades ` width ` y ` height `. Por ejemplo, el siguiente código crea un elemento Canvas2D que tiene un área de dibujo con una altura de 100 píxeles y una anchura de 200 píxeles:

import QtCanvas2D

Canvas2D {
    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);
    }
}

Consejos para portar aplicaciones HTML5 Canvas existentes

Aunque el elemento Canvas proporciona una API similar a la de HTML5, las aplicaciones HTML5 Canvas deben modificarse para ejecutarse en el elemento Canvas:

  • Sustituye todas las llamadas a la API DOM por enlaces de propiedades QML o métodos del elemento Canvas.
  • Sustituye todos los controladores de eventos HTML por el elemento « MouseArea ».
  • Cambia las llamadas a las funciones `setInterval`/`setTimeout` por el elemento ` FrameAnimation ` o por el uso de ` requestAnimationFrame()`.
  • Coloca el código de dibujo en el controlador « onPaint » y activa el dibujo llamando a los métodos « markDirty()» o « requestPaint()».
  • Para dibujar imágenes, cárgalas llamando al método loadImage() del Canvas y, a continuación, solicita que se dibujen en el controlador onImageLoaded.

Véase también Canvas2DContext, QCanvasPainterItem y QCanvasPainter.

Documentación de propiedades

available : bool

Indica cuándo Canvas puede proporcionar un contexto de dibujo sobre el que operar.

context : object

Contiene el contexto de dibujo activo.

Si el lienzo está listo y se ha realizado correctamente una llamada a ` getContext()` o se ha establecido la propiedad ` contextType ` con un tipo de contexto compatible, esta propiedad contendrá el contexto de dibujo actual; en caso contrario, será `null`.

contextType : string

El tipo de contexto de dibujo que se va a utilizar.

Esta propiedad se establece con el nombre del tipo de contexto activo.

Si se establece explícitamente, el lienzo intentará crear un contexto del tipo indicado en cuanto esté disponible.

El nombre del tipo es el mismo que se utiliza en la llamada a getContext(), en el caso del lienzo 2D el valor será «2d».

Véase también getContext() y available.

Documentación de Signal

imageLoaded()

Esta señal se emite cuando se ha cargado una imagen.

Nota: El controlador correspondiente es onImageLoaded.

Véase también loadImage().

paint(rect region)

Esta señal se emite cuando es necesario renderizar el region. Si hay un contexto activo, se puede acceder a él a través de la propiedad «context».

Esta señal puede activarse mediante markDirty(), requestPaint() o al cambiar la ventana de lienzo actual.

Nota: El controlador correspondiente es ` onPaint`.

painted()

Esta señal se emite una vez que se han ejecutado todos los comandos de dibujo del contexto y se ha renderizado el Canvas.

Nota: El controlador correspondiente es onPainted.

Documentación del método

void cancelRequestAnimationFrame(int handle)

Esta función cancelará la función de devolución de llamada de animación a la que hace referencia handle.

object getContext(string contextId, ... args)

Devuelve un contexto de dibujo o, en caso de que no haya ninguno disponible, un objeto ` null `.

El parámetro « contextId » identifica el contexto requerido. El elemento « Canvas2D » devolverá un contexto que implemente el modo de dibujo requerido. Tras la primera llamada a «getContext», cualquier llamada posterior a «getContext» con el mismo «contextId» devolverá el mismo objeto de contexto. Actualmente se ignoran los argumentos adicionales (args).

Si el tipo de contexto no es compatible o si previamente se ha solicitado al lienzo que proporcione un tipo de contexto diferente e incompatible, se devolverá un error de « null ».

Canvas2D Solo admite un contexto 2D.

bool isImageError(url image)

Devuelve « true » si no se ha podido cargar « image »; en caso contrario, devuelve « false ».

Véase también loadImage().

bool isImageLoaded(url image)

Devuelve «true» si el objeto ` image ` se ha cargado correctamente y está listo para su uso.

Véase también loadImage().

bool isImageLoading(url image)

Devuelve «true» si el elemento « image » se está cargando en ese momento.

Véase también loadImage().

void loadImage(url image, size sourceSize = undefined)

Carga de forma asíncrona el archivo image indicado.

Una vez que la imagen esté lista, se emitirá la señal « imageLoaded()». La imagen cargada se puede descargar con el método « unloadImage()».

Nota: Solo las imágenes cargadas se pueden dibujar en el elemento « Canvas2D ».

Si se especifica sourceSize, la imagen se escalará a ese tamaño durante la carga. Esto resulta útil para cargar imágenes escalables (vectoriales) (p. ej., SVG) al tamaño de visualización previsto.

Véase también unloadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData() y Context2D::drawImage().

void markDirty()

Marca el lienzo como sucio. Esto activará la señal « paint ».

Véase también paint y requestPaint().

int requestAnimationFrame(callback)

Esta función programa la llamada a « callback » antes de componer la escena « Qt Quick ».

void requestPaint()

Solicita que se vuelva a dibujar toda la región visible.

Véase también markDirty().

void unloadImage(url image)

Descarga la imagen « image ».

Una vez que se ha descargado una imagen, el contexto del lienzo no puede dibujarla a menos que se vuelva a cargar.

Véanse también loadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData() y Context2D::drawImage.

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