HTMLCanvasElement: getContext()-Methode

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

Die HTMLCanvasElement.getContext()-Methode gibt einen Zeichenkontext auf dem <canvas> zurück oder null, wenn der Kontextbezeichner nicht unterstützt wird oder das <canvas> bereits auf einen anderen Kontextmodus gesetzt wurde.

Spätere Aufrufe dieser Methode auf demselben Canvas-Element mit demselben contextType-Argument geben immer dieselbe Zeichnungskontextinstanz zurück, die beim ersten Aufruf der Methode zurückgegeben wurde. Es ist nicht möglich, ein anderes Zeichnungskontextobjekt auf einem gegebenen Canvas-Element zu erhalten.

Syntax

js
getContext(contextType)
getContext(contextType, contextAttributes)

Parameter

contextType

Ein String, der den Kontextbezeichner enthält und den Zeichenkontext definiert, der mit dem <canvas> verbunden ist. Mögliche Werte sind:

"2d"

Erstellt ein CanvasRenderingContext2D-Objekt, das einen zweidimensionalen Zeichenkontext darstellt.

"webgl" (oder "experimental-webgl")

Erstellt ein WebGLRenderingContext-Objekt, das einen dreidimensionalen Zeichenkontext darstellt. Dieser Kontext ist nur in Browsern verfügbar, die WebGL Version 1 (OpenGL ES 2.0) implementieren.

"webgl2"

Erstellt ein WebGL2RenderingContext-Objekt, das einen dreidimensionalen Zeichenkontext darstellt. Dieser Kontext ist nur in Browsern verfügbar, die WebGL Version 2 (OpenGL ES 3.0) implementieren.

"webgpu"

Erstellt ein GPUCanvasContext-Objekt, das einen dreidimensionalen Zeichenkontext für WebGPU-Render-Pipelines darstellt. Dieser Kontext ist nur in Browsern verfügbar, die The WebGPU API implementieren.

"bitmaprenderer"

Erstellt ein ImageBitmapRenderingContext, das nur die Funktionalität bietet, den Inhalt des <canvas> durch ein gegebenes ImageBitmap zu ersetzen.

Hinweis: Der Bezeichner "experimental-webgl" wird in neuen Implementierungen von WebGL verwendet. Diese Implementierungen haben entweder die Konformität der Test-Suite noch nicht erreicht, oder die Grafiktreiber auf der Plattform sind noch nicht stabil. Die Khronos Group zertifiziert WebGL- Implementierungen unter bestimmten Konformitätsregeln.

contextAttributes Optional

Sie können mehrere Kontextattribute verwenden, wenn Sie Ihren Zeichenkontext erstellen, zum Beispiel:

js
const gl = canvas.getContext("webgl", {
  antialias: false,
  depth: false,
});

2D-Kontext-Attribute:

alpha

Ein boolescher Wert, der angibt, ob das <canvas> einen Alpha-Kanal enthält. Wenn auf false gesetzt, weiß der Browser nun, dass der Hintergrund immer undurchsichtig ist, was das Zeichnen von transparentem Inhalt und Bildern beschleunigen kann.

colorSpace Optional

Gibt den Farbraum des Zeichenkontextes an. Mögliche Werte sind:

desynchronized

Ein boolescher Wert, der dem Nutzeragenten signalisiert, die Latenz zu verringern, indem der Canvas-Malzyklus von der Ereignisschleife getrennt wird.

willReadFrequently

Ein boolescher Wert, der anzeigt, ob viele Rücklese-Operationen geplant sind. Dies wird die Verwendung eines softwarebasierten (anstelle hardwarebeschleunigten) 2D-Canvas erzwingen und kann Speicher sparen, wenn getImageData() häufig aufgerufen wird.

WebGL-Kontext-Attribute:

alpha

Ein boolescher Wert, der angibt, ob das <canvas> einen Alpha-Puffer enthält.

depth

Ein boolescher Wert, der angibt, dass der Zeichenpuffer verlangt, einen Tiefenpuffer von mindestens 16 Bit zu haben.

stencil

Ein boolescher Wert, der angibt, dass der Zeichenpuffer verlangt, einen Schablonenpuffer von mindestens 8 Bit zu haben.

desynchronized

Ein boolescher Wert, der dem Nutzeragenten signalisiert, die Latenz zu verringern, indem der Canvas-Malzyklus von der Ereignisschleife getrennt wird.

antialias

Ein boolescher Wert, der angibt, ob Anti-Aliasing, wenn möglich, durchgeführt werden soll.

failIfMajorPerformanceCaveat

Ein boolescher Wert, der angibt, ob ein Kontext erstellt wird, wenn die Systemleistung niedrig ist oder keine Hardware-GPU verfügbar ist.

powerPreference

Ein Hinweis an den Nutzeragenten, welche Konfiguration der GPU für den WebGL-Kontext geeignet ist. Mögliche Werte sind:

"default"

Der Nutzeragent entscheidet, welche GPU-Konfiguration am besten geeignet ist. Dies ist der Standardwert.

"high-performance"

Priorisiert die Renderleistung gegenüber dem Stromverbrauch.

"low-power"

Priorisiert die Stromersparnis gegenüber der Renderleistung.

premultipliedAlpha

Ein boolescher Wert, der angibt, dass der Seitengestalter annimmt, dass der Zeichenpuffer Farben mit vormultipliziertem Alpha enthält.

preserveDrawingBuffer

Wenn der Wert auf true gesetzt ist, werden die Puffer nicht gelöscht und behalten ihre Werte bei, bis sie vom Autor gelöscht oder überschrieben werden.

xrCompatible

Ein boolescher Wert, der dem Nutzeragenten signalisiert, einen kompatiblen Grafikadapter für ein immersives XR-Gerät zu verwenden. Das Setzen dieses synchronen Flags bei der Kontext-Erstellung wird nicht empfohlen; es sollte stattdessen die asynchrone Methode WebGLRenderingContext.makeXRCompatible() aufgerufen werden, sobald Sie beabsichtigen, eine XR-Sitzung zu starten.

Hinweis: Die WebGPU-Spezifikation definiert keine spezifischen Kontextattribute für getContext(). Stattdessen bietet sie Konfigurationsoptionen über die GPUCanvasContext.configure()-Methode.

Rückgabewert

Ein Zeichenkontext, der entweder ein

Wenn der Kontextbezeichner nicht unterstützt wird oder das <canvas> bereits auf einen anderen Kontextmodus gesetzt wurde, wird null zurückgegeben.

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn das <canvas> seine Kontrolle durch den Aufruf von HTMLCanvasElement.transferControlToOffscreen() auf ein Offscreen-Element übertragen hat.

Beispiele

Gegeben dieses <canvas>-Element:

html
<canvas id="canvas" width="300" height="300"></canvas>

Können Sie einen 2d-Kontext des <canvas> mit folgendem Code erhalten:

js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
console.log(ctx); // CanvasRenderingContext2D { /* … */ }

Nun haben Sie den 2D-Zeichenkontext für ein <canvas> und können darin zeichnen.

Spezifikationen

Specification
HTML
# dom-canvas-getcontext-dev

Browser-Kompatibilität

Siehe auch