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
- available : bool
- context : object
- contextType : string
Señales
- imageLoaded()
- paint(rect region)
- painted()
Métodos
- void cancelRequestAnimationFrame(int handle)
- object getContext(string contextId, ... args)
- bool isImageError(url image)
- bool isImageLoaded(url image)
- bool isImageLoading(url image)
- void loadImage(url image, size sourceSize)
- void markDirty()
- int requestAnimationFrame(callback)
- void requestPaint()
- void unloadImage(url image)
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.