Signatur
Beschreibung
Die schreibgeschützte Eigenschaft selectedIndex der Schnittstelle ImageTrackList gibt als Ganzzahl an, welcher Track eines Bildes gerade zum Dekodieren ausgewählt ist. Eine ImageTrackList bekommst du über ImageDecoder.tracks. Sie ist Teil der WebCodecs API.
Manche Bildformate enthalten mehrere Tracks, zum Beispiel AVIF-Dateien mit einem Standbild und zusätzlich einer Animation. Der ImageDecoder dekodiert immer nur den ausgewählten Track. Mit selectedIndex findest du heraus, welcher das ist, etwa um die passende Anzahl von Frames (frameCount) zu ermitteln oder um die Auswahl in einer Oberfläche anzuzeigen.
Den Wert kannst du nicht direkt setzen. Um einen anderen Track auszuwählen, setzt du die Eigenschaft selected des gewünschten ImageTrack auf true. Danach ändert sich selectedIndex entsprechend. Setzt du selected des aktuellen Tracks auf false, ist kein Track mehr ausgewählt und der Wert wird -1.
Zuverlässig ist der Wert erst, wenn das Promise ImageTrackList.ready erfüllt ist. Vorher wurden die Metadaten des Bildes eventuell noch nicht gelesen.
Rückgabewert
ImageTrackList, oder -1, wenn kein Track ausgewählt ist.Beispiele
Ausgewählten Track eines animierten Bildes ermitteln
const response = await fetch('/bilder/animation.gif');
const decoder = new ImageDecoder({
data: response.body,
type: 'image/gif'
});
// Warten, bis die Track-Informationen gelesen wurden
await decoder.tracks.ready;
const { selectedIndex, length } = decoder.tracks;
console.log(`Track ${selectedIndex} von ${length} ausgewählt`);
const track = decoder.tracks[selectedIndex];
console.log('Animiert:', track.animated, '| Frames:', track.frameCount);Zwischen Tracks einer AVIF-Datei wechseln
const response = await fetch('/bilder/sequenz.avif');
const decoder = new ImageDecoder({
data: await response.arrayBuffer(),
type: 'image/avif'
});
await decoder.tracks.ready;
console.log('Vorher:', decoder.tracks.selectedIndex);
// Den ersten animierten Track suchen und auswählen
for (let i = 0; i < decoder.tracks.length; i++) {
if (decoder.tracks[i].animated) {
decoder.tracks[i].selected = true;
break;
}
}
console.log('Nachher:', decoder.tracks.selectedIndex);
// Ersten Frame des neu ausgewählten Tracks dekodieren
const { image } = await decoder.decode({ frameIndex: 0 });
console.log(image.displayWidth, image.displayHeight);
image.close();Auswahl aufheben und auf -1 prüfen
const decoder = new ImageDecoder({
data: await (await fetch('/bilder/logo.png')).arrayBuffer(),
type: 'image/png'
});
await decoder.tracks.ready;
const tracks = decoder.tracks;
tracks.selectedTrack.selected = false; // Auswahl aufheben
if (tracks.selectedIndex === -1) {
console.log('Kein Track ausgewählt – decode() ist nicht möglich.');
}
decoder.close();// Wichtig · Fallstricke
- Nur lesbar: Eine Zuweisung an
selectedIndexhat keine Wirkung (im Strict Mode wirft sie einenTypeError). Die Auswahl änderst du immer überImageTrack.selected. - Zeitpunkt: Lies den Wert erst nach
await decoder.tracks.ready. Vorher kann die Liste leer sein und der Wert-1lauten. - Wert
-1: Ist kein Track ausgewählt, ist auchselectedTrackgleichnull, unddecoder.decode()schlägt fehl. Prüfe diesen Fall, bevor du den Index zum Zugriff auf die Liste verwendest (tracks[-1]ergibtundefined). - Trackwechsel: Wählst du einen anderen Track aus, verwirft der Decoder bereits dekodierte Frames und noch ausstehende
decode()-Aufrufe. - Kompatibilität:
ImageDecoderund damitImageTrackListgibt es in Chromium-Browsern ab Version 94 und in neueren Firefox-Versionen, in Safari nicht. Die API ist nur in sicheren Kontexten (HTTPS) verfügbar. Prüfe vor der Nutzung mit'ImageDecoder' in globalThis, ob sie vorhanden ist.