Signatur
Beschreibung
Die Eigenschaft selected gehört zum Interface ImageTrack aus der WebCodecs-API. Eine Bilddatei kann mehrere Spuren enthalten, zum Beispiel ein Standbild und zusätzlich eine animierte Sequenz, wie es bei manchen AVIF-Dateien der Fall ist. Ein ImageDecoder dekodiert immer nur die Spur, deren selected-Wert true ist. Alle Aufrufe von decode() gelten also für diese Spur.
Du kannst die Eigenschaft lesen und schreiben. Setzt du sie auf true, wird diese Spur ausgewählt und die bisher ausgewählte Spur verliert ihre Auswahl, denn es kann immer nur eine Spur ausgewählt sein. Setzt du die ausgewählte Spur auf false, ist anschließend keine Spur mehr ausgewählt: ImageTrackList.selectedIndex ist dann -1, und decode() schlägt fehl, bis du wieder eine Spur auswählst.
Typische Einsatzfälle sind das Umschalten zwischen Standbild und Animation, eine gezielte Auswahl der Spur mit den meisten Frames oder die Prüfung, welche Spur der Decoder standardmäßig ausgewählt hat. Die Spurliste ist erst gültig, nachdem das Promise decoder.tracks.ready erfüllt wurde.
Rückgabewert
true, wenn die Spur zum Dekodieren ausgewählt ist, sonst false. Wenn du den Wert setzt, änderst du die Auswahl im zugehörigen ImageDecoder.Beispiele
Ausgewählte Spur einer Bilddatei ermitteln
const response = await fetch('/bilder/animation.avif');
const decoder = new ImageDecoder({
data: response.body,
type: 'image/avif'
});
// Die Spurliste erst nach tracks.ready verwenden
await decoder.tracks.ready;
for (let i = 0; i < decoder.tracks.length; i++) {
const track = decoder.tracks[i];
console.log(`Spur ${i}: animiert=${track.animated}, ausgewählt=${track.selected}`);
}Auf die Standbild-Spur umschalten und dekodieren
const response = await fetch('/bilder/animation.avif');
const decoder = new ImageDecoder({ data: response.body, type: 'image/avif' });
await decoder.tracks.ready;
// Erste nicht animierte Spur suchen
const standbild = Array.from(
{ length: decoder.tracks.length },
(_, i) => decoder.tracks[i]
).find((track) => !track.animated);
if (standbild && !standbild.selected) {
standbild.selected = true; // hebt die Auswahl der anderen Spur auf
}
const { image } = await decoder.decode({ frameIndex: 0 });
const canvas = document.querySelector('canvas');
canvas.getContext('2d').drawImage(image, 0, 0);
image.close();
console.log('Ausgewählte Spur:', decoder.tracks.selectedIndex);Auswahl aufheben und wiederherstellen
const response = await fetch('/bilder/animiert.gif');
const decoder = new ImageDecoder({ data: response.body, type: 'image/gif' });
await decoder.tracks.ready;
const track = decoder.tracks.selectedTrack;
track.selected = false;
console.log(decoder.tracks.selectedIndex); // keine Spur mehr ausgewählt
try {
await decoder.decode();
} catch (err) {
console.log('Dekodieren fehlgeschlagen:', err.name);
}
track.selected = true;
console.log(decoder.tracks.selectedIndex);// Wichtig · Fallstricke
- Browserunterstützung:
ImageDecodergibt es in Chromium-Browsern ab Version 94 und in Firefox ab Version 133, aber nicht in Safari. Prüfe die Unterstützung vorher mit'ImageDecoder' in window. Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung, dafür aber auch in Web Workern. - Zeitpunkt: Lies oder setze
selectederst nachawait decoder.tracks.ready. Vorher ist die Spurliste möglicherweise leer. - Nur eine Auswahl: Setzt du eine Spur auf
true, verlieren alle anderen Spuren automatisch ihre Auswahl. Setzt du die aktive Spur auffalse, ist keine Spur mehr ausgewählt, unddecode()wird abgelehnt. - Laufende Dekodierungen: Beim Wechsel der Spur werden noch ausstehende
decode()-Promises abgelehnt. Starte die Dekodierung erst nach dem Umschalten. - Geschlossener Decoder: Nach
decoder.close()hat das Setzen vonselectedkeine Wirkung. ImageDecoder.isTypeSupported(type)sagt dir, ob der Browser ein Format (etwa AVIF) überhaupt dekodieren kann.