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.

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 dem gleichen Canvas-Element mit dem gleichen contextType-Argument werden immer dieselbe Instanz des Zeichenkontexts zurückgeben, die beim ersten Aufruf der Methode zurückgegeben wurde. Es ist nicht möglich, ein anderes Zeichenkontextobjekt auf einem gegebenen Canvas-Element zu erhalten.

Syntax

js
getContext(contextType)
getContext(contextType, contextAttributes)

Parameter

contextType

Ein String, der den Kontextbezeichner enthält, der den mit dem Canvas verbundenen Zeichenkontext definiert. 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-Renderpipelines darstellt. Dieser Kontext ist nur in Browsern verfügbar, die The WebGPU API implementieren.

"bitmaprenderer"

Erstellt einen ImageBitmapRenderingContext, der nur Funktionalität zum Ersetzen des Canvas-Inhalts mit einem gegebenen ImageBitmap bietet.

Hinweis: Der Bezeichner "experimental-webgl" wird in neuen Implementierungen von WebGL verwendet. Diese Implementierungen haben entweder noch nicht die Testsuiten-Konformität 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 beim Erstellen Ihres Zeichenkontexts verwenden, zum Beispiel:

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

2d-Kontextattribute:

alpha

Ein boolescher Wert, der angibt, ob das Canvas einen Alphakanal enthält. Wenn false gesetzt ist, 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 Zeichenkontexts an. Mögliche Werte sind:

desynchronized

Ein boolescher Wert, der den Benutzeragenten anweist, die Latenz zu verringern, indem der Canvas-Zeichenzyklus vom Ereignisloop desynchronisiert wird.

willReadFrequently

Ein boolescher Wert, der angibt, ob viele Ausleseoperationen geplant sind. Dies erzwingt die Verwendung eines Software- (anstelle eines hardwarebeschleunigten) 2D-Canvas und kann Speicher sparen, wenn getImageData() häufig aufgerufen wird.

WebGL-Kontextattribute:

alpha

Ein boolescher Wert, der angibt, ob das Canvas einen Alphapuffer enthält.

depth

Ein boolescher Wert, der anzeigt, dass der Zeichenpuffer einen Tiefenpuffer von mindestens 16 Bit haben soll.

stencil

Ein boolescher Wert, der anzeigt, dass der Zeichenpuffer einen Schablonenpuffer von mindestens 8 Bit haben soll.

desynchronized

Ein boolescher Wert, der den Benutzeragenten anweist, die Latenz zu verringern, indem der Canvas-Zeichenzyklus vom Ereignisloop desynchronisiert wird.

antialias

Ein boolescher Wert, der angibt, ob Antialiasing nach Möglichkeit durchgeführt werden soll.

failIfMajorPerformanceCaveat

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

powerPreference

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

"default"

Überlässt dem Benutzeragenten die Entscheidung, welche GPU-Konfiguration am besten geeignet ist. Dies ist der Standardwert.

"high-performance"

Priorisiert die Renderleistung gegenüber dem Stromverbrauch.

"low-power"

Priorisiert den Stromverbrauch gegenüber der Renderleistung.

premultipliedAlpha

Ein boolescher Wert, der angibt, dass der Seitenkompositor davon ausgehen wird, dass der Zeichenpuffer Farben mit vor-multipliziertem Alpha enthält.

preserveDrawingBuffer

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

xrCompatible

Ein boolescher Wert, der den Benutzeragenten darauf hinweist, einen kompatiblen Grafikadapter für ein immersives XR-Gerät zu verwenden. Das Setzen dieser synchronen Markierung bei der Kontexterstellung wird nicht empfohlen; stattdessen sollte 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 Methode GPUCanvasContext.configure() an.

Rückgabewert

Ein Zeichenkontext, der entweder ist:

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 über einen Aufruf von HTMLCanvasElement.transferControlToOffscreen() übertragen hat.

Beispiele

Gegeben ist dieses <canvas> Element:

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

Sie können einen 2d-Kontext des Canvas mit folgendem Code erhalten:

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

Jetzt haben Sie den 2D-Zeichenkontext für ein Canvas und können darin zeichnen.

Spezifikationen

Specification
HTML Standard
# dom-canvas-getcontext-dev

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch