ImageBitmapRenderingContext.canvas — Eigenschaft · JavaScript-Referenz

Signatur

get ImageBitmapRenderingContext.canvas

Beschreibung

Die Eigenschaft canvas eines ImageBitmapRenderingContext gibt die Zeichenfläche zurück, von der der Kontext über getContext("bitmaprenderer") angefordert wurde. Im Hauptthread ist das ein HTMLCanvasElement, in einem Worker oder bei Offscreen-Rendering ein OffscreenCanvas.

Nützlich ist die Eigenschaft vor allem, wenn eine Funktion nur den Kontext bekommt, aber trotzdem auf die Zeichenfläche zugreifen muss, etwa um width/height auszulesen, das Element im DOM einzuhängen oder den Inhalt mit toBlob() bzw. convertToBlob() zu exportieren. So muss man Kontext und Canvas nicht doppelt weiterreichen.

Die Eigenschaft kann nur gelesen werden. Eine Zuweisung hat keine Wirkung (im Strict Mode gibt es einen TypeError). Ein Kontext bleibt immer an genau eine Zeichenfläche gebunden.

Rückgabewert

Typ

HTMLCanvasElement | OffscreenCanvas

Beschreibung

Die Zeichenfläche, zu der der Kontext gehört: ein HTMLCanvasElement, wenn der Kontext von einem DOM-Canvas stammt, sonst ein OffscreenCanvas.

Beispiele

Zugehöriges Canvas-Element ermitteln

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

console.log(ctx.canvas === canvas);
console.log(ctx.canvas instanceof HTMLCanvasElement);

true true

Bitmap übertragen und Canvas über den Kontext anpassen

const showBitmap = async (ctx, url) => {
  const blob = await (await fetch(url)).blob();
  const bitmap = await createImageBitmap(blob);

  // Canvas-Größe über ctx.canvas an die Bitmap anpassen
  ctx.canvas.width = bitmap.width;
  ctx.canvas.height = bitmap.height;

  ctx.transferFromImageBitmap(bitmap);
  console.log(`Angezeigt: ${ctx.canvas.width}x${ctx.canvas.height}`);
};

const ctx = document.createElement("canvas").getContext("bitmaprenderer");
document.body.append(ctx.canvas);
await showBitmap(ctx, "/bilder/foto.png");

Angezeigt: 800x600

OffscreenCanvas: Inhalt als Blob exportieren

const offscreen = new OffscreenCanvas(200, 100);
const ctx = offscreen.getContext("bitmaprenderer");

const quelle = new OffscreenCanvas(200, 100);
const ctx2d = quelle.getContext("2d");
ctx2d.fillStyle = "teal";
ctx2d.fillRect(0, 0, 200, 100);

ctx.transferFromImageBitmap(quelle.transferToImageBitmap());

// ctx.canvas ist hier ein OffscreenCanvas
const blob = await ctx.canvas.convertToBlob({ type: "image/png" });
console.log(ctx.canvas instanceof OffscreenCanvas, blob.type);

true image/png

// Wichtig · Fallstricke

Den Rückgabetyp vorher prüfen: HTMLCanvasElement hat toBlob() und toDataURL(), OffscreenCanvas dagegen convertToBlob(). Wer gemeinsamen Code für beide schreibt, sollte das mit instanceof unterscheiden.
Die Eigenschaft kann nur gelesen werden. ctx.canvas = andereCanvas hat keine Wirkung (im Strict Mode TypeError).
Wird ein HTMLCanvasElement mit transferControlToOffscreen() übergeben, verweist ein Kontext im Worker auf das OffscreenCanvas und nicht auf das DOM-Element.
Ändert man width oder height über ctx.canvas, wird die Zeichenfläche wie bei jedem Canvas zurückgesetzt. Die Größe also vor transferFromImageBitmap() setzen.
Kompatibilität: wird von allen modernen Browsern unterstützt. OffscreenCanvas als Rückgabetyp gibt es in Safari erst ab Version 16.4.

Siehe auch

WebGLRenderingContext.canvas CanvasRenderingContext2D.canvas CanvasRenderingContext2D.lang CanvasRenderingContext2D.font CanvasRenderingContext2D.lineCap