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
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 gegebenenImageBitmap
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:
jsconst 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 auffalse
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:
"srgb"
wählt den sRGB-Farbraum. Dies ist der Standardwert."display-p3"
wählt den display-p3-Farbraum.
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, wenngetImageData()
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 dieGPUCanvasContext.configure()
Methode.
Rückgabewert
Ein Zeichenkontext, der entweder ein
CanvasRenderingContext2D
für"2d"
,WebGLRenderingContext
für"webgl"
und"experimental-webgl"
,WebGL2RenderingContext
für"webgl2"
,GPUCanvasContext
für"webgpu"
,ImageBitmapRenderingContext
für"bitmaprenderer"
ist.
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 vonHTMLCanvasElement.transferControlToOffscreen()
auf eine Offscreen-Instanz übertragen hat.
Beispiele
Angenommen, dieses <canvas>
-Element:
<canvas id="canvas" width="300" height="300"></canvas>
Sie können einen 2d
-Kontext des <canvas>
mit folgendem Code erhalten:
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
HTMLCanvasElement
: Schnittstelle zur Definition derHTMLCanvasElement.getContext()
-MethodeOffscreenCanvas.getContext()
CanvasRenderingContext2D.getContextAttributes()
,WebGLRenderingContext.getContextAttributes()
-
CanvasRenderingContext2D
,ImageBitmapRenderingContext
,WebGLRenderingContext
,WebGL2RenderingContext
,GPUCanvasContext
: Verfügbare Zeichenkontexte - DCI-P3-Farbraum auf Wikipedia
- sRGB-Farbraum auf Wikipedia