CanvasRenderingContext2D.getContextAttributes() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.getContextAttributes()

Beschreibung

Mit getContextAttributes() fragen Sie ab, mit welchen Einstellungen ein 2D-Zeichenkontext tatsächlich erzeugt wurde. Diese Einstellungen übergeben Sie beim Aufruf von canvas.getContext("2d", { ... }) als zweites Argument. Die Methode liefert die vom Browser wirklich angewendeten Werte zurück, nicht einfach Ihre Eingabe. Nicht unterstützte Optionen fallen weg oder werden durch Standardwerte ersetzt.

Das zurückgegebene Objekt (CanvasRenderingContext2DSettings) enthält typischerweise:

alpha: ob das Canvas einen Alphakanal hat. Bei false ist der Hintergrund deckend, was der Browser beim Rendern optimieren kann.
colorSpace: der Farbraum, "srgb" oder "display-p3".
desynchronized: ob der Kontext vom Ereigniszyklus entkoppelt ist, damit weniger Verzögerung entsteht (etwa bei Zeichen-Apps).
willReadFrequently: ob der Kontext für häufiges Auslesen mit getImageData() optimiert ist, meist durch Rendern auf der CPU statt der GPU.
In neueren Browsern teils auch colorType ("unorm8" oder "float16").

Die Methode ist vor allem nützlich, um Funktionen zur Laufzeit zu erkennen und Fehler zu suchen. So prüfen Sie, ob ein angeforderter Farbraum wie Display-P3 wirklich aktiv ist oder ob der Browser eine Option stillschweigend ignoriert hat.

Rückgabewert

Typ

CanvasRenderingContext2DSettings

Beschreibung

Ein einfaches Objekt mit den Eigenschaften alpha (boolean), colorSpace ("srgb" | "display-p3"), desynchronized (boolean) und willReadFrequently (boolean), in neueren Browsern ggf. auch colorType. Das Objekt ist eine Kopie: Wenn Sie es ändern, ändert sich der Kontext nicht.

Beispiele

Standard-Attribute eines 2D-Kontexts auslesen

const canvas = document.createElement("canvas");
const ctx = canvas.getContext("2d");

console.log(ctx.getContextAttributes());

{ alpha: true, colorSpace: "srgb", desynchronized: false, willReadFrequently: false }

Eigene Optionen setzen und Ergebnis prüfen

const canvas = document.querySelector("#zeichenflaeche");
const ctx = canvas.getContext("2d", {
  alpha: false,
  willReadFrequently: true
});

const { alpha, willReadFrequently } = ctx.getContextAttributes();
console.log(`Alpha: ${alpha}, häufiges Auslesen: ${willReadFrequently}`);

Alpha: false, häufiges Auslesen: true

Display-P3 anfordern, sonst auf sRGB zurückfallen

const createWideGamutContext = (canvas) => {
  const ctx = canvas.getContext("2d", { colorSpace: "display-p3" });
  const { colorSpace } = ctx.getContextAttributes();

  if (colorSpace !== "display-p3") {
    console.warn("Display-P3 nicht verfügbar, verwende sRGB.");
  }
  return { ctx, colorSpace };
};

const { colorSpace } = createWideGamutContext(document.createElement("canvas"));
console.log("Aktiver Farbraum:", colorSpace);

Aktiver Farbraum: display-p3 (bzw. "srgb" mit Warnung in Browsern ohne P3-Unterstützung)

Vorher prüfen, ob die Methode vorhanden ist

const ctx = document.createElement("canvas").getContext("2d");

const attrs = typeof ctx.getContextAttributes === "function"
  ? ctx.getContextAttributes()
  : { alpha: true, colorSpace: "srgb" }; // angenommene Standardwerte

console.log(attrs.alpha);

true

// Wichtig · Fallstricke

Nur beim Erzeugen festlegbar: Die Attribute gelten ab dem ersten Aufruf von getContext("2d", options). Spätere Aufrufe mit anderen Optionen geben denselben Kontext zurück und ignorieren die neuen Optionen. Mit getContextAttributes() sehen Sie, welche Werte wirklich gelten.
Browser-Kompatibilität: Chrome kennt die Methode schon lange. Firefox unterstützt sie erst ab Version 110, Safari ab 16.4. Für ältere Browser brauchen Sie eine Prüfung wie im letzten Beispiel. Welche Eigenschaften enthalten sind, unterscheidet sich je nach Browser. colorType ist neu, desynchronized wird nicht überall wirklich umgesetzt.
Nicht mit WebGL verwechseln: WebGLRenderingContext.getContextAttributes() liefert andere Attribute (antialias, depth, stencil usw.) und kann null zurückgeben, wenn der Kontext verloren gegangen ist.
Leistung: Setzen Sie willReadFrequently: true nur, wenn Sie wirklich oft getImageData() aufrufen. Sonst kann der Kontext auf der CPU landen und Zeichenoperationen werden langsamer.
Auch OffscreenCanvasRenderingContext2D hat diese Methode, zum Beispiel in Web Workern.

Siehe auch

CanvasRenderingContext2D.isContextLost() CanvasRenderingContext2D.getImageData() CanvasRenderingContext2D.getLineDash() CanvasRenderingContext2D.clearRect() CanvasRenderingContext2D.createConicGradient()