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.

* 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 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
# dom-canvas-getcontext-dev

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
getContext
2d context
options.alpha parameter
options.colorSpace parameter
options.desynchronized parameter
options.willReadFrequently parameter
bitmaprenderer context
options.alpha parameter
WebGL2 context
options.alpha parameter
options.desynchronized parameter
options.failIfMajorPerformanceCaveat parameter
options.powerPreference parameter
WebGL context
options.alpha parameter
options.desynchronized parameter
options.failIfMajorPerformanceCaveat parameter
options.powerPreference parameter
webgpu context
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
Uses a non-standard name.
Has more compatibility info.

Siehe auch