ImageDecoder.complete — Eigenschaft · JavaScript-Referenz

Signatur

get ImageDecoder.prototype.complete

Beschreibung

Die Eigenschaft ImageDecoder.complete gehört zur WebCodecs API. Sie ist ein boolescher Wert und zeigt an, ob der Decoder die codierten Bilddaten (z. B. GIF, PNG, WebP, AVIF, JPEG) vollständig empfangen und gepuffert hat. Solange noch Daten nachgeladen werden, ist der Wert false.

Wie wichtig das ist, hängt von der Datenquelle ab: Übergibt man dem Konstruktor im Feld data einen ArrayBuffer, ein TypedArray oder eine DataView, liegen alle Daten sofort vor, und complete ist praktisch sofort true. Übergibt man dagegen einen ReadableStream (etwa response.body aus fetch()), wird complete erst true, wenn der Stream vollständig gelesen ist.

Praktisch relevant ist das vor allem bei animierten Bildern, die gestreamt werden: Dort kann sich ImageTrack.frameCount noch erhöhen, solange Daten eintreffen. Erst mit complete === true stehen Frame-Anzahl und Metadaten endgültig fest. Mit complete fragt man den aktuellen Zustand synchron ab. Zum Warten nimmt man das Promise ImageDecoder.completed, das erfüllt wird, sobald complete auf true wechselt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn alle codierten Bilddaten gepuffert sind, sonst false. Die Eigenschaft ist schreibgeschützt.

Beispiele

ArrayBuffer als Quelle: Daten liegen sofort vor

const response = await fetch('/bilder/logo.png');
const buffer = await response.arrayBuffer();

const decoder = new ImageDecoder({ data: buffer, type: 'image/png' });

// Bei einem ArrayBuffer sind alle Daten schon da
console.log('Vollständig gepuffert:', decoder.complete);

const { image } = await decoder.decode();
console.log(`Größe: ${image.displayWidth}×${image.displayHeight}`);
image.close();
decoder.close();

Vollständig gepuffert: true Größe: 256×256

Gestreamtes GIF: Zustand vor und nach dem Laden prüfen

const response = await fetch('/bilder/animation.gif');

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

console.log('Direkt nach dem Erzeugen:', decoder.complete);

// Auf das vollständige Puffern warten
await decoder.completed;
console.log('Nach completed:', decoder.complete);

await decoder.tracks.ready;
console.log('Frames insgesamt:', decoder.tracks.selectedTrack.frameCount);
decoder.close();

Direkt nach dem Erzeugen: false Nach completed: true Frames insgesamt: 24

Frames abspielen, solange noch Daten nachgeladen werden

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 track = decoder.tracks.selectedTrack;

let index = 0;
while (true) {
  // Nur wenn alles gepuffert ist, ist frameCount endgültig
  if (decoder.complete && index >= track.frameCount) break;

  try {
    const { image } = await decoder.decode({ frameIndex: index });
    ctx.drawImage(image, 0, 0);
    await new Promise((r) => setTimeout(r, (image.duration ?? 100000) / 1000));
    image.close();
    index++;
  } catch (err) {
    // Frame existiert (noch) nicht, z. B. nach vollständigem Laden außer Bereich
    if (decoder.complete) break;
    throw err;
  }
}
console.log(`${index} Frames abgespielt, complete = ${decoder.complete}`);
decoder.close();

24 Frames abgespielt, complete = true

// Wichtig · Fallstricke

Kein Ereignis: complete löst beim Wechsel kein Event aus. Wer auf das Ende des Ladens reagieren will, sollte await decoder.completed nutzen, statt den Wert in einer Schleife abzufragen.
Nicht gleichbedeutend mit „dekodiert“: true heißt nur, dass die codierten Daten gepuffert sind. Dekodiert wird erst durch decode().
Fehlerfall: Bricht der Stream ab oder sind die Daten ungültig, wird completed abgewiesen. complete kann dann dauerhaft false bleiben. Deshalb completed immer mit try/catch abfangen.
Nach close() ist der Decoder nicht mehr verwendbar. Der Wert von complete ist dann nicht mehr aussagekräftig.
Kompatibilität: ImageDecoder gibt es in Chromium-Browsern (ab 94) und in Firefox (ab 133), nicht in Safari. Die API ist nur in sicheren Kontexten (HTTPS) verfügbar, auch in Workern. Vorher mit 'ImageDecoder' in globalThis und ImageDecoder.isTypeSupported(type) prüfen.

Siehe auch

ImageDecoder ImageDecoder.completed ImageDecoder.prototype.decode() ImageDecoder.tracks ImageTrack.frameCount ImageDecoder.isTypeSupported() ReadableStream