ImageDecoder.reset() — Methode · JavaScript-Referenz

Signatur

ImageDecoder.prototype.reset()

Beschreibung

Die Methode reset() gehört zum Interface ImageDecoder der WebCodecs-API. Sie bricht alle noch nicht abgeschlossenen decode()-Aufrufe ab. Jedes zugehörige Promise wird mit einer DOMException vom Typ AbortError abgelehnt.

Anders als close() gibt reset() den Decoder nicht frei. Die Instanz bleibt nutzbar: Nach dem Zurücksetzen kannst du sofort neue decode()-Aufrufe starten, zum Beispiel für ein anderes Einzelbild (Frame) einer animierten Grafik. Die Bilddaten und die Spurinformationen (tracks) bleiben erhalten.

Typische Einsatzfälle:

Der Nutzer springt in einer Animation schnell zu einem anderen Frame. Veraltete Dekodier-Aufträge sollen dann nicht mehr fertig laufen.
Die Ansicht wird gewechselt oder eine Komponente wird ausgeblendet. Laufende Arbeit soll abgebrochen werden, ohne den Decoder neu anzulegen.
Du willst eine Warteschlange von Dekodier-Aufträgen verwerfen, bevor du neue Aufträge mit höherer Priorität startest.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Ausstehende decode()-Promises werden mit einem AbortError abgelehnt.

Beispiele

Laufende Dekodierung abbrechen und AbortError abfangen

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

const pending = decoder.decode({ frameIndex: 5 });

// Auftrag sofort wieder abbrechen
decoder.reset();

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

AbortError

Schnelles Springen zwischen Frames (nur der letzte Auftrag zählt)

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const response = await fetch('/bilder/animation.webp');
const decoder = new ImageDecoder({ data: response.body, type: 'image/webp' });
await decoder.tracks.ready;

const showFrame = async (frameIndex) => {
  // Veraltete Aufträge verwerfen
  decoder.reset();
  try {
    const { image } = await decoder.decode({ frameIndex });
    ctx.drawImage(image, 0, 0);
    image.close(); // VideoFrame freigeben
  } catch (err) {
    if (err.name !== 'AbortError') throw err;
  }
};

const slider = document.querySelector('#frame-slider');
slider.addEventListener('input', () => showFrame(Number(slider.value)));

Decoder nach reset() weiterverwenden

const blob = await (await fetch('/bilder/foto.png')).blob();
const decoder = new ImageDecoder({ data: blob.stream(), type: 'image/png' });

decoder.decode().catch((e) => console.log('Abgebrochen:', e.name));
decoder.reset();

// Die Instanz ist weiterhin gültig
const { image } = await decoder.decode();
console.log(image.displayWidth, image.displayHeight);
image.close();
decoder.close();

Abgebrochen: AbortError 1920 1080

// Wichtig · Fallstricke

Ablehnungen immer abfangen: Jedes offene decode()-Promise wird abgelehnt. Wenn du das nicht abfängst, erscheinen unhandledrejection-Warnungen. Prüfe im catch gezielt auf err.name === 'AbortError'.
Geschlossener Decoder: Wurde vorher close() aufgerufen, wirft reset() eine DOMException vom Typ InvalidStateError.
reset() ist nicht close(): Die Ressourcen des Decoders werden nicht freigegeben. Wenn du ihn nicht mehr brauchst, rufe zusätzlich close() auf. Bereits gelieferte VideoFrame-Objekte musst du selbst mit image.close() freigeben.
Kompatibilität: ImageDecoder ist nur in sicheren Kontexten (HTTPS) verfügbar, funktioniert aber auch in Workern. Chromium-Browser unterstützen es ab Version 94, Firefox ab 133. Safari unterstützt es derzeit nicht. Prüfe die Unterstützung vorher mit 'ImageDecoder' in globalThis.

Siehe auch

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