HTMLCanvasElement: Methode getContext()

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 eingestellt wurde.

Spätere Aufrufe dieser Methode auf demselben <canvas>-Element mit demselben contextType-Argument geben immer dieselbe Zeichenkontextinstanz zurück, wie sie 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 dem <canvas> zugeordneten Zeichenkontext definiert. Mögliche Werte sind:

"2d"

Erstellt ein CanvasRenderingContext2D-Objekt, das einen zweidimensionalen Zeichenkontext repräsentiert.

"webgl" (oder "experimental-webgl")

Erstellt ein WebGLRenderingContext-Objekt, das einen dreidimensionalen Zeichenkontext repräsentiert. 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 repräsentiert. 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 repräsentiert. Dieser Kontext ist nur in Browsern verfügbar, die Die WebGPU API implementieren.

"bitmaprenderer"

Erstellt einen ImageBitmapRenderingContext, der nur die Funktionalität bietet, den Inhalt des <canvas> mit einem gegebenen ImageBitmap zu ersetzen.

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

contextAttributes Optional

Es können mehrere Kontextattribute bei der Erstellung Ihres Zeichenkontexts verwendet werden, 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 Alphakanal 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 Zeichenkontexts an. Mögliche Werte sind:

desynchronized

Ein boolescher Wert, der dem Benutzerdienstprogramm vorschlägt, die Latenz zu reduzieren, indem der Zeichenzyklus des <canvas> vom Event-Loop desynchronisiert wird.

willReadFrequently

Ein boolescher Wert, der angibt, ob viele Rückleseoperationen geplant sind. Dies erzwingt die Verwendung eines Software- (anstatt eines hardwarebeschleunigten) 2D-<canvas> und kann Speicher sparen, wenn getImageData() häufig aufgerufen wird.

WebGL-Kontext-Attribute:

alpha

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

depth

Ein boolescher Wert, der angibt, dass der Zeichenpuffer einen Tiefenpuffer mit mindestens 16 Bit haben soll.

stencil

Ein boolescher Wert, der angibt, dass der Zeichenpuffer einen Stencilpuffer mit mindestens 8 Bit haben soll.

desynchronized

Ein boolescher Wert, der dem Benutzerdienstprogramm vorschlägt, die Latenz zu reduzieren, indem der Zeichenzyklus des <canvas> vom Event-Loop desynchronisiert wird.

antialias

Ein boolescher Wert, der angibt, ob, wenn möglich, eine Kantenglättung vorgenommen 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 das Benutzerdienstprogramm, welche Konfiguration der GPU für den WebGL-Kontext geeignet ist. Mögliche Werte sind:

"default"

Lässt das Benutzerdienstprogramm entscheiden, welche GPU-Konfiguration am besten geeignet ist. Dies ist der Standardwert.

"high-performance"

Priorisiert die Zeichenleistung über den Stromverbrauch.

"low-power"

Priorisiert die Stromersparnis über die Zeichenleistung.

premultipliedAlpha

Ein boolescher Wert, der angibt, dass der Seitenkompositor annimmt, dass der Zeichenpuffer Farben mit vor-multiplizierter Alpha enthält.

preserveDrawingBuffer

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

xrCompatible

Ein boolescher Wert, der dem Benutzerdienstprogramm nahelegt, eine kompatible Grafikkarte für ein immersives XR-Gerät zu verwenden. Das Setzen dieses synchronen Flags bei der Kontext-Erstellung wird nicht empfohlen; stattdessen sollte die asynchrone Methode WebGLRenderingContext.makeXRCompatible() aufgerufen werden, wenn Sie beabsichtigen, eine XR-Sitzung zu starten.

Hinweis: Die WebGPU-Spezifikation definiert keine spezifischen Kontextattribute für getContext(). Stattdessen bietet sie Konfigurationsmöglichkeiten ü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 eingestellt wurde, wird null zurückgegeben.

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn das <canvas> die Kontrolle durch Aufruf von HTMLCanvasElement.transferControlToOffscreen() auf eine Offscreen-Instanz übertragen hat.

Beispiele

Angenommen, 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 { /* … */ }

Nun 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