Signatur
Beschreibung
Der Konstruktor TrackEvent() erstellt ein Ereignisobjekt vom Typ TrackEvent. Solche Ereignisse lösen Browser normalerweise selbst aus, wenn in einer Track-Liste eines Medienelements ein Track hinzukommt oder entfernt wird. Die zugehörigen Ereignistypen sind addtrack und removetrack.
Die wichtigste Eigenschaft ist track. Sie verweist auf den betroffenen AudioTrack, VideoTrack oder TextTrack. Wenn du das Ereignis selbst erzeugst, übergibst du diesen Track im Initialisierungsobjekt.
Selbst erzeugte TrackEvent-Objekte brauchst du vor allem in Unit-Tests, in eigenen Medien-Playern oder bei Polyfills. Damit kannst du das Verhalten von addtrack- und removetrack-Listenern nachstellen, ohne echte Mediendateien zu laden. Das Ereignis verschickst du mit dispatchEvent().
Ein selbst ausgelöstes Ereignis verändert die Track-Liste nicht. Es informiert nur die registrierten Listener. Die Eigenschaft isTrusted ist dabei immer false.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses, zum Beispiel "addtrack" oder "removetrack". Groß- und Kleinschreibung werden unterschieden. |
|
| $eventInitDict | object | {} | Optionales Initialisierungsobjekt. Es enthält die Felder von EventInit (bubbles, cancelable, composed, jeweils Standardwert false) und zusätzlich track: einen AudioTrack, VideoTrack, TextTrack oder null (Standardwert null). |
Rückgabewert
TrackEvent-Objekt. Seine Eigenschaft track ist der übergebene Track oder null.Beispiele
TrackEvent erzeugen und Eigenschaften prüfen
const video = document.createElement('video');
const textTrack = video.addTextTrack('subtitles', 'Deutsch', 'de');
const event = new TrackEvent('addtrack', { track: textTrack });
console.log(event.type);
console.log(event.track.label);
console.log(event.isTrusted);addtrack-Listener in einem Test simulieren
const video = document.createElement('video');
const tracks = video.textTracks;
const onAddTrack = (e) => {
console.log(`Neuer Track: ${e.track.kind} (${e.track.language})`);
};
tracks.addEventListener('addtrack', onAddTrack);
// Track erzeugen (der Browser feuert dabei selbst ein addtrack-Ereignis, asynchron)
const track = video.addTextTrack('captions', 'Englisch', 'en');
// Ereignis zusätzlich manuell auslösen, z. B. im Unit-Test
tracks.dispatchEvent(new TrackEvent('addtrack', { track }));
tracks.removeEventListener('addtrack', onAddTrack);Fehlendes track-Feld abfangen
const event = new TrackEvent('removetrack');
const handleRemove = (e) => {
if (!e.track) {
console.warn('removetrack ohne Track-Referenz');
return;
}
console.log(`Entfernt: ${e.track.label}`);
};
handleRemove(event);// Wichtig · Fallstricke
- Nur ein Ereignis, keine Änderung an der Liste: Ein selbst ausgelöstes
TrackEventfügt keinen Track hinzu und entfernt keinen. Die Liste bleibt, wie sie ist. - Typ von
track: Du kannst nur echteAudioTrack-,VideoTrack- oderTextTrack-Objekte übergeben. Normale Objekte führen zu einemTypeError. Es gibt keinen Konstruktor fürTextTrack. Erzeuge Text-Tracks deshalb mitHTMLMediaElement.addTextTrack(). - Browser-Unterstützung:
TextTrackListund der Konstruktor funktionieren in allen modernen Browsern.audioTracksundvideoTracksunterstützt dagegen im Wesentlichen nur Safari. In Chrome sind sie nur über ein Feature-Flag verfügbar, in Firefox nur über eine Einstellung. Prüfe die Unterstützung vorher, zum Beispiel mit'audioTracks' in HTMLMediaElement.prototype. - Kein Bubbling: Track-Listen stehen nicht im DOM-Baum. Registriere Listener deshalb direkt an der Liste, also mit
video.textTracks.addEventListener(...)oder über die Eigenschaftonaddtrack/onremovetrack. - Das
addtrack-Ereignis, das der Browser beiaddTextTrack()selbst auslöst, kommt asynchron als Task. Listener sollten also nicht davon ausgehen, dass es sofort eintrifft.