En esta página

Canvas QML Type

Proporciona un elemento de lienzo 2D que permite dibujar mediante JavaScript. Más...

Import Statement: import QtQuick
Inherits:

Item

Propiedades

Señales

Métodos

Descripción detallada

El elemento Canvas 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, sombras, degradados y patrones, así como realizar operaciones de píxeles a bajo nivel. El resultado de Canvas se puede guardar como un archivo de imagen o serializarse en una URL.

La representación en el «Canvas» se realiza mediante un objeto « Context2D », normalmente como resultado de la señal « paint ».

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

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

Actualmente, el elemento Canvas solo admite el contexto de representación bidimensional.

Renderizado multihilo y destino de renderizado

En Qt 6.0, el elemento Canvas admite un único destino de renderizado: Canvas.Image.

El destino de renderizado « Canvas.Image » es un objeto « QImage ». Este destino de renderizado admite el renderizado en un hilo en segundo plano, lo que permite ejecutar operaciones de dibujo complejas o de larga duración sin bloquear la interfaz de usuario. Este es el único destino de renderizado compatible con todos los backends de « Qt Quick ».

El destino de renderizado predeterminado es `Canvas.Image` y el ` renderStrategy ` predeterminado es `Canvas.Immediate`.

Operaciones con píxeles

Se admiten todas las operaciones de píxeles del contexto 2D de HTML5. Para garantizar un mejor rendimiento en la lectura y escritura de píxeles, se debe elegir el destino de renderizado « Canvas.Image ».

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 que se ejecuten en el elemento Canvas:

  • Sustituye todas las llamadas a la API DOM por enlaces de propiedades QML o métodos del elemento Canvas.
  • Sustituya todos los controladores de eventos HTML por el elemento « MouseArea ».
  • Cambia las llamadas a las funciones setInterval/setTimeout por el elemento « Timer » o 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() de Canvas y, a continuación, solicita que se dibujen en el controlador onImageLoaded.

A partir de Qt 5.4, el Canvas es un texture provider y puede utilizarse directamente en ShaderEffects y otras clases que utilicen proveedores de texturas.

Nota: En general, se deben evitar los lienzos de gran tamaño, las actualizaciones frecuentes y las animaciones con el destino de renderizado `Canvas.Image`. Esto se debe a que, con las API gráficas aceleradas, cada actualización conlleva una carga de textura. Además, si es posible, es preferible utilizar ` QQuickPaintedItem ` e implementar el dibujo en C++ mediante ` QPainter `, en lugar del enfoque con JavaScript y ` Context2D `, que resulta más costoso y probablemente menos eficaz.

Véase también Context2D, QQuickPaintedItem y Qt Quick Ejemplos: controladores de punteros.

Documentación de propiedades

available : bool [read-only]

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

canvasSize : size

Almacena el tamaño lógico del lienzo sobre el que dibuja el contexto.

Por defecto, el tamaño del lienzo es el mismo que el del elemento de lienzo actual.

Al configurar canvasSize, tileSize y canvasWindow, el elemento Canvas puede actuar como un gran lienzo virtual con muchos rectángulos de mosaico renderizados por separado. El motor de renderizado de Canvas solo pinta los mosaicos que se encuentran dentro de la ventana actual del lienzo.

Véase también tileSize y canvasWindow.

context : object [read-only]

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(), para el lienzo 2D el valor será «2d».

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

renderStrategy : enumeration

Almacena la estrategia de renderizado actual del lienzo.

ConstanteDescripción
Canvas.ImmediateEl contexto ejecutará los comandos gráficos inmediatamente en el hilo principal de la interfaz de usuario.
Canvas.ThreadedEl contexto aplazará los comandos gráficos a un hilo de renderizado privado.
Canvas.CooperativeEl contexto aplazará los comandos gráficos al hilo de renderizado global de la aplicación.

Esta indicación se proporciona junto con ` renderTarget ` al contexto gráfico para determinar el método de renderizado. Es posible que un contexto gráfico no admita `renderStrategy`, ` renderTarget ` o una combinación de ambas; en tal caso, el contexto elegirá las opciones adecuadas y `Canvas` notificará el cambio a las propiedades.

Las pruebas de configuración o en tiempo de ejecución pueden provocar que el grafo de escena QML se renderice en el hilo de la interfaz gráfica de usuario. Seleccionar ` Canvas.Cooperative` no garantiza que el renderizado se produzca en un hilo distinto del hilo de la interfaz gráfica de usuario.

El valor por defecto es ` Canvas.Immediate`.

Véase también renderTarget.

renderTarget : enumeration

Almacena el destino de renderizado del lienzo actual.

ConstanteDescripción
Canvas.ImageRenderiza en un búfer de imagen en memoria.
Canvas.FramebufferObjectA partir de Qt 6.0, este valor se ignora.

Esta indicación se proporciona junto con ` renderStrategy ` al contexto gráfico para determinar el método de renderizado. Es posible que un contexto gráfico no admita ` renderStrategy`, `renderTarget` o una combinación de ambos; en tal caso, el contexto elegirá las opciones adecuadas y `Canvas` notificará el cambio a las propiedades.

El destino de renderizado predeterminado es Canvas.Image.

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 retorno de llamada de animación a la que hace referencia handle.

Context2D getContext(string contextId, ... args)

Devuelve un contexto de dibujo o un ` null ` si no hay ningún contexto disponible.

El parámetro ` contextId ` identifica el contexto requerido. El elemento `Canvas` 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 «canvas» que proporcione un tipo de contexto diferente e incompatible, se devolverá « null ».

Canvas 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 ` 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 especificado.

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

Si se especifica sourceSize, la imagen se escalará a ese tamaño durante la carga. Esto resulta útil para cargar imágenes escalables (vectoriales) (por ejemplo, SVG) en el tamaño de visualización previsto. Este parámetro se introdujo en Qt 6.7.

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

void markDirty(rect area)

Marca el elemento « area » como modificado, de modo que, cuando esta zona esté visible, el renderizador del lienzo la vuelva a dibujar. 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().

bool save(string filename, size imageSize = undefined)

Guarda el contenido actual del lienzo en un archivo de imagen filename. El formato de la imagen guardada se determina automáticamente según el sufijo de filename. Devuelve true si la operación se realiza con éxito. Si se especifica imageSize, la imagen resultante tendrá este tamaño y una relación de píxeles del dispositivo (devicePixelRatio) de 1.0. En caso contrario, se aplica a la imagen guardada la función devicePixelRatio() de la ventana en la que se muestra el lienzo.

Nota: Al llamar a este método se forzará el dibujo de todo el lienzo, no solo de la ventana visible del lienzo actual.

Véase también canvasWindow, canvasSize y toDataURL().

string toDataURL(string mimeType)

Devuelve una URL de datos para la imagen del lienzo.

El valor predeterminado de mimeType es «image/png».

Véase también save().

void unloadImage(url image)

Descarga la imagen ` image`.

Una vez descargada una imagen, el contexto del lienzo no podrá dibujarla a menos que se vuelva a cargar.

Véase 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.