Back to Qt.io
Contact Us Blog Download Qt

Canvas QML Type

Stellt ein 2D-Canvas-Element bereit, das das Zeichnen über JavaScript ermöglicht. Mehr...

Import Statement: import QtQuick
Inherits:

Item

Eigenschaften

Signale

Methoden

Detaillierte Beschreibung

Das Element Canvas ermöglicht das Zeichnen von geraden und gekrümmten Linien, einfachen und komplexen Formen, Diagrammen und referenzierten Grafiken. Es kann auch Text, Farben, Schatten, Farbverläufe und Muster hinzufügen und Pixeloperationen auf niedriger Ebene durchführen. Die Canvas-Ausgabe kann als Bilddatei gespeichert oder zu einer URL serialisiert werden.

Die Darstellung auf dem Canvas erfolgt über ein Context2D Objekt, in der Regel als Ergebnis des paint Signals.

Um einen Zeichenbereich im Canvas-Element zu definieren, setzen Sie die Eigenschaften width und height. Der folgende Code erstellt beispielsweise ein Canvas-Element, das eine Zeichenfläche mit einer Höhe von 100 Pixeln und einer Breite von 200 Pixeln hat:

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

Derzeit unterstützt das Canvas-Element nur den zweidimensionalen Rendering-Kontext.

Threaded Rendering und Render Target

In Qt 6.0 unterstützt das Canvas-Element ein Renderziel: Canvas.Image.

Das Renderziel Canvas.Image ist ein QImage Objekt. Dieses Rendering-Ziel unterstützt das Rendering in einem Hintergrund-Thread, so dass komplexe oder lang andauernde Malvorgänge ausgeführt werden können, ohne die Benutzeroberfläche zu blockieren. Dies ist das einzige Rendering-Ziel, das von allen Qt Quick Backends unterstützt wird.

Das Standard-Rendering-Ziel ist Canvas.Image und das Standard renderStrategy ist Canvas.Immediate.

Pixel-Operationen

Alle HTML5 2D-Kontext-Pixeloperationen werden unterstützt. Um eine verbesserte Leistung beim Lesen/Schreiben von Pixeln zu gewährleisten, sollte das Rendering-Ziel Canvas.Image gewählt werden.

Tipps für die Portierung bestehender HTML5-Canvas-Anwendungen

Obwohl das Canvas-Element eine HTML5-ähnliche API bereitstellt, müssen HTML5-Canvas-Anwendungen für die Ausführung im Canvas-Element angepasst werden:

  • Ersetzen Sie alle DOM-API-Aufrufe durch QML-Eigenschaftsbindungen oder Canvas-Elementmethoden.
  • Ersetzen Sie alle HTML-Ereignishandler durch das Element MouseArea.
  • Ersetzen Sie die Funktionsaufrufe setInterval/setTimeout durch das Element Timer oder die Verwendung von requestAnimationFrame().
  • Platzieren Sie den Malcode in den onPaint -Handler und lösen Sie das Malen durch den Aufruf der Methoden markDirty() oder requestPaint() aus.
  • Um Bilder zu zeichnen, laden Sie sie durch den Aufruf der Methode loadImage() des Canvas und fordern Sie sie dann im onImageLoaded Handler zum Malen an.

Ab Qt 5.4 ist der Canvas ein texture provider und kann direkt in ShaderEffects und anderen Klassen verwendet werden, die Texturanbieter verwenden.

Hinweis: Im Allgemeinen sollten große Leinwände, häufige Aktualisierungen und Animationen mit dem Canvas.Image Rendering Target vermieden werden. Dies liegt daran, dass bei beschleunigten Grafik-APIs jede Aktualisierung zu einem Textur-Upload führen wird. Bevorzugen Sie außerdem, wenn möglich, QQuickPaintedItem und implementieren Sie das Zeichnen in C++ über QPainter anstelle des teureren und wahrscheinlich weniger leistungsfähigen Ansatzes mit JavaScript und Context2D.

Siehe auch Context2D, QQuickPaintedItem, und Qt Quick Beispiele - Pointer Handlers.

Eigenschaft Dokumentation

available : bool [read-only]

Zeigt an, ob Canvas einen Zeichenkontext für die Bearbeitung bereitstellen kann.


canvasSize : size

Enthält die logische Leinwandgröße, auf der der Kontext malt.

Standardmäßig ist die Leinwandgröße dieselbe Größe wie die aktuelle Größe des Canvas-Elements.

Durch die Einstellung von canvasSize, tileSize und canvasWindow kann das Canvas-Element als große virtuelle Leinwand mit vielen separat gerenderten Kachelrechtecken fungieren. Nur die Kacheln innerhalb des aktuellen Canvas-Fensters werden von der Canvas-Rendering-Engine gezeichnet.

Siehe auch tileSize und canvasWindow.


context : object [read-only]

Enthält den aktiven Zeichenkontext.

Wenn der Canvas bereit ist und ein erfolgreicher Aufruf von getContext() erfolgt ist oder die Eigenschaft contextType mit einem unterstützten Kontexttyp gesetzt wurde, enthält diese Eigenschaft den aktuellen Zeichenkontext, andernfalls null.


contextType : string

Der Typ des zu verwendenden Zeichenkontextes.

Diese Eigenschaft wird auf den Namen des aktiven Kontexttyps gesetzt.

Wenn sie explizit gesetzt ist, versucht der Canvas, einen Kontext des genannten Typs zu erstellen, sobald er verfügbar ist.

Der Name des Typs ist derselbe, der im Aufruf getContext() verwendet wird; für den 2D-Canvas lautet der Wert "2d".

Siehe auch getContext() und available.


renderStrategy : enumeration

Enthält die aktuelle Canvas-Rendering-Strategie.

KonstanteBeschreibung
Canvas.Immediatecontext führt Grafikbefehle sofort im Haupt-UI-Thread aus.
Canvas.Threadedcontext verschiebt Grafikbefehle auf einen privaten Rendering-Thread.
Canvas.Cooperativecontext verschiebt Grafikbefehle auf den globalen Rendering-Thread der Anwendung.

Dieser Hinweis wird zusammen mit renderTarget an den Grafikkontext übergeben, um die Rendering-Methode zu bestimmen. Es kann sein, dass eine RenderStrategie, renderTarget oder eine Kombination von einem Grafikkontext nicht unterstützt wird. In diesem Fall wählt der Kontext die entsprechenden Optionen und Canvas signalisiert die Änderung der Eigenschaften.

Konfigurations- oder Laufzeittests können dazu führen, dass der QML-Szenengraph im GUI-Thread gerendert wird. Die Auswahl von Canvas.Cooperative garantiert nicht, dass das Rendering in einem vom GUI-Thread getrennten Thread erfolgt.

Der Standardwert ist Canvas.Immediate.

Siehe auch renderTarget.


renderTarget : enumeration

Enthält das aktuelle Canvas-Rendering-Ziel.

KonstanteBeschreibung
Canvas.ImageRendert in einen speicherinternen Bildpuffer.
Canvas.FramebufferObjectAb Qt 6.0 wird dieser Wert ignoriert.

Dieser Hinweis wird zusammen mit renderStrategy an den Grafikkontext übergeben, um die Renderingmethode zu bestimmen. Es kann sein, dass renderStrategy, renderTarget oder eine Kombination davon von einem Grafikkontext nicht unterstützt wird. In diesem Fall wählt der Kontext die entsprechenden Optionen und Canvas signalisiert die Änderung der Eigenschaften.

Das Standard-Rendering-Ziel ist Canvas.Image.


Signal Dokumentation

imageLoaded()

Dieses Signal wird ausgesendet, wenn ein Bild geladen wurde.

Hinweis: Der entsprechende Handler ist onImageLoaded.

Siehe auch loadImage().


paint(rect region)

Dieses Signal wird ausgegeben, wenn das region gerendert werden muss. Wenn ein Kontext aktiv ist, kann dieser über die Eigenschaft context referenziert werden.

Dieses Signal kann durch markDirty(), requestPaint() oder durch die Änderung des aktuellen Canvas-Fensters ausgelöst werden.

Hinweis: Der entsprechende Handler ist onPaint.


painted()

Dieses Signal wird ausgegeben, nachdem alle Befehle zur Kontextmalerei ausgeführt wurden und der Canvas gerendert wurde.

Hinweis: Der entsprechende Handler ist onPainted.


Dokumentation der Methode

cancelRequestAnimationFrame(int handle)

Diese Funktion bricht den Animations-Callback ab, der von handle referenziert wird.


object getContext(string contextId, ... args)

Gibt einen Zeichenkontext zurück, oder null, wenn kein Kontext verfügbar ist.

Der Parameter contextId benennt den gewünschten Kontext. Das Canvas-Element gibt einen Kontext zurück, der den gewünschten Zeichenmodus implementiert. Nach dem ersten Aufruf von getContext gibt jeder weitere Aufruf von getContext mit der gleichen contextId das gleiche Kontextobjekt zurück. Alle zusätzlichen Argumente (args) werden derzeit ignoriert.

Wenn der Kontexttyp nicht unterstützt wird oder der Canvas zuvor aufgefordert wurde, einen anderen und inkompatiblen Kontexttyp bereitzustellen, wird null zurückgegeben.

Canvas unterstützt nur einen 2d-Kontext.


isImageError(url image)

Gibt true zurück, wenn image nicht geladen werden konnte, andernfalls false.

Siehe auch loadImage().


isImageLoaded(url image)

Gibt true zurück, wenn image erfolgreich geladen wurde und bereit zur Verwendung ist.

Siehe auch loadImage().


isImageLoading(url image)

Gibt true zurück, wenn die Datei image gerade geladen wird.

Siehe auch loadImage().


loadImage(url image, size sourceSize = undefined)

Lädt das angegebene image asynchron.

Sobald das Bild fertig ist, wird das Signal imageLoaded() ausgegeben. Das geladene Bild kann mit der Methode unloadImage() wieder entladen werden.

Hinweis: Nur geladene Bilder können auf das Canvas-Element gemalt werden.

Wenn sourceSize angegeben ist, wird das Bild beim Laden auf diese Größe skaliert. Dies ist nützlich für das Laden von skalierbaren (Vektor-)Bildern (z.B. SVGs) in der vorgesehenen Anzeigegröße. Dieser Parameter wurde in Qt 6.7 eingeführt.

Siehe auch unloadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData(), und Context2D::drawImage().


markDirty(rect area)

Markiert den angegebenen Bereich area als schmutzig, so dass der Canvas-Renderer ihn neu zeichnet, wenn dieser Bereich sichtbar ist. Dadurch wird das Signal paint ausgelöst.

Siehe auch paint und requestPaint().


int requestAnimationFrame(callback)

Diese Funktion plant den Aufruf von callback vor dem Zusammenstellen der Szene Qt Quick.


requestPaint()

Fordert an, dass der gesamte sichtbare Bereich neu gezeichnet wird.

Siehe auch markDirty().


bool save(string filename, size imageSize = undefined)

Speichert den aktuellen Leinwandinhalt in eine Bilddatei filename. Das Format des gespeicherten Bildes wird automatisch durch das Suffix von filename bestimmt. Gibt bei Erfolg true zurück. Wenn imageSize angegeben ist, hat das resultierende Bild diese Größe und ein devicePixelRatio von 1.0. Andernfalls wird das devicePixelRatio() des Fensters, in dem die Leinwand angezeigt wird, auf das gespeicherte Bild angewendet.

Hinweis: Der Aufruf dieser Methode erzwingt die Bemalung der gesamten Leinwand, nicht nur des aktuell sichtbaren Fensters der Leinwand.

Siehe auch canvasWindow, canvasSize, und toDataURL().


string toDataURL(string mimeType)

Gibt eine Daten-URL für das Bild im Canvas zurück.

Die Voreinstellung mimeType ist "image/png".

Siehe auch save().


unloadImage(url image)

Entlädt das image.

Sobald ein Bild entladen ist, kann es nicht mehr vom Canvas-Kontext gezeichnet werden, bis es erneut geladen wird.

Siehe auch loadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData(), und 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.