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 der Leinwand zurück oder null, wenn der Kontext-Bezeichner nicht unterstützt wird oder die Leinwand bereits auf einen anderen Kontextmodus gesetzt wurde.

Spätere Aufrufe dieser Methode auf demselben Canvas-Element mit demselben contextType-Argument geben immer dieselbe Zeichenkontextinstanz zurück wie beim ersten Aufruf der Methode. 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 Kontext-Bezeichner enthält, der den Zeichenkontext definiert, der dem Canvas zugeordnet 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 Die WebGPU-API implementieren.

"bitmaprenderer"

Erstellt einen ImageBitmapRenderingContext, der lediglich 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 der 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

Sie können mehrere Kontext-Attribute 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 jetzt, 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:

colorType Optional

Gibt den Farbtyp des Zeichenkontexts an. Mögliche Werte sind:

  • "unorm8" stellt die Farblaufkanäle auf 8-Bit-Unsigned-Werte. Dies ist der Standardwert.
  • "float16" stellt die Farblaufkanäle auf 16-Bit-Gleitpunktwerte.
desynchronized

Ein boolescher Wert, der dem Benutzeragenten einen Hinweis gibt, die Latenz zu verringern, indem der Zeichenzyklus des Canvas von der Ereignisschleife desynchronisiert wird.

willReadFrequently

Ein boolescher Wert, der angibt, ob viele Rückleseoperationen geplant sind. Dies zwingt 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 Alpha-Puffer enthält.

depth

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

stencil

Ein boolescher Wert, der angibt, dass der Zeichenpuffer einen Stencil-Puffer von mindestens 8 Bit haben soll.

desynchronized

Ein boolescher Wert, der dem Benutzeragenten einen Hinweis gibt, die Latenz zu verringern, indem der Zeichenzyklus des Canvas von der Ereignisschleife desynchronisiert wird.

antialias

Ein boolescher Wert, der angibt, ob Anti-Aliasing, falls 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 Benutzeragenten, welche GPU-Konfiguration für den WebGL-Kontext geeignet ist. Mögliche Werte sind:

"default"

Überlassen Sie dem Benutzeragenten die Entscheidung, welche GPU-Konfiguration am geeignetesten ist. Dies ist der Standardwert.

"high-performance"

Bevorzugt die Rendering-Leistung gegenüber dem Stromverbrauch.

"low-power"

Bevorzugt Energiesparen gegenüber der Rendering-Leistung.

premultipliedAlpha

Ein boolescher Wert, der angibt, dass der Seitenkompositor davon ausgeht, dass der Zeichenpuffer Farben mit vorkomponiertem Alpha enthält.

preserveDrawingBuffer

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

xrCompatible

Ein boolescher Wert, der dem Benutzeragenten einen Hinweis gibt, einen kompatiblen Grafikadapter für ein immersives XR-Gerät zu verwenden. Das Setzen dieses synchronen Flags bei der Kontext-Erstellung wird abgeraten; rufen Sie stattdessen die asynchrone Methode WebGLRenderingContext.makeXRCompatible() auf, sobald Sie beabsichtigen, eine XR-Sitzung zu starten.

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

Rückgabewert

Ein Zeichenkontext, der entweder ein

Wenn der Kontext-Bezeichner 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 die Kontrolle an ein Offscreen-Element übertragen hat, indem es HTMLCanvasElement.transferControlToOffscreen() aufgerufen hat.

Beispiele

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

Browser-Kompatibilität

Siehe auch