ImageDecoder.close() — Methode · JavaScript-Referenz

Signatur

ImageDecoder.prototype.close()

Beschreibung

Die Methode close() der Schnittstelle ImageDecoder aus der WebCodecs API beendet den Decoder endgültig. Alle Aufträge, die noch in der Warteschlange stehen, werden abgebrochen. Interne Puffer, dekodierte Daten und gegebenenfalls reservierte Hardware-Decoder werden sofort freigegeben. Man muss also nicht warten, bis der Garbage Collector aufräumt.

Das ist vor allem dann wichtig, wenn viele Bilder nacheinander dekodiert werden, etwa in Bildergalerien, bei Vorschaubildern oder beim Verarbeiten animierter GIF-, WebP- oder AVIF-Dateien in einem Worker. Dekoder-Ressourcen sind begrenzt und belegen oft viel Speicher außerhalb des JavaScript-Heaps. Deshalb sollte man close() aufrufen, sobald man den Decoder nicht mehr braucht. Am besten geschieht das in einem finally-Block.

Nach dem Aufruf ist der Decoder dauerhaft unbrauchbar:

Noch offene decode()-Promises werden mit einer DOMException vom Typ AbortError abgelehnt.
Spätere Aufrufe von decode() liefern ein abgelehntes Promise mit InvalidStateError.
Ein weiterer Aufruf von close() hat keine Wirkung.

Wer noch einmal dekodieren will, muss einen neuen ImageDecoder erzeugen.

Rückgabewert

Typ

undefined

Beschreibung

Die Methode gibt keinen Wert zurück.

Beispiele

Ersten Frame dekodieren und Decoder sauber schließen

const zeigeErstesBild = async (url, canvas) => {
  const response = await fetch(url);
  const decoder = new ImageDecoder({
    data: response.body,
    type: response.headers.get('Content-Type') ?? 'image/gif'
  });

  try {
    const { image } = await decoder.decode({ frameIndex: 0 });
    const ctx = canvas.getContext('2d');
    canvas.width = image.displayWidth;
    canvas.height = image.displayHeight;
    ctx.drawImage(image, 0, 0);
    image.close(); // VideoFrame ebenfalls freigeben
  } finally {
    decoder.close(); // Ressourcen immer freigeben, auch bei Fehlern
  }
};

await zeigeErstesBild('/bilder/animation.gif', document.querySelector('canvas'));

Laufenden Dekodiervorgang abbrechen

const response = await fetch('/bilder/gross.avif');
const decoder = new ImageDecoder({ data: response.body, type: 'image/avif' });

const auftrag = decoder.decode({ frameIndex: 0 });

// Nutzer verlässt z. B. die Ansicht, bevor das Bild fertig ist
decoder.close();

try {
  await auftrag;
} catch (err) {
  console.log(err.name);
}

AbortError

Aufruf nach close() schlägt fehl

const bytes = await (await fetch('/bilder/logo.png')).arrayBuffer();
const decoder = new ImageDecoder({ data: bytes, type: 'image/png' });

decoder.close();
decoder.close(); // zweiter Aufruf: ohne Wirkung, kein Fehler

decoder.decode().catch((err) => console.log(err.name));

InvalidStateError

// Wichtig · Fallstricke

VideoFrames separat schließen: close() am Decoder gibt die schon gelieferten VideoFrame-Objekte aus decode() nicht frei. Für jeden Frame muss man zusätzlich image.close() aufrufen, sonst bleibt Speicher belegt. Chrome warnt in diesem Fall in der Konsole.
Nicht umkehrbar: Nach close() ist der Decoder dauerhaft geschlossen. Einen Befehl zum erneuten Öffnen gibt es nicht. Für neue Dekodiervorgänge braucht man eine neue Instanz.
Offene Promises: Ausstehende decode()-Aufrufe werden mit AbortError abgelehnt. Diesen Fall sollte man mit catch abfangen, damit keine unbehandelten Promise-Ablehnungen entstehen.
Browser-Unterstützung: ImageDecoder gibt es in Chromium-Browsern ab Version 94 und in neueren Firefox-Versionen. Safari unterstützt die Schnittstelle bisher nicht. Vorher prüfen, z. B. mit 'ImageDecoder' in globalThis. Die API funktioniert nur in sicheren Kontexten (HTTPS) und auch in Web Workern.

Siehe auch

ImageDecoder.reset() new ImageDecoder() ImageDecoder.decode() ImageDecoder.isTypeSupported() AudioDecoder.close()