HTMLMediaElement.controlsList — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.controlsList

Beschreibung

Die Eigenschaft controlsList spiegelt das HTML-Attribut controlslist von <audio>- und <video>-Elementen wider. Sie liefert eine DOMTokenList, über die du einzelne Steuerelemente der eingebauten Browser-Bedienleiste ausblenden kannst. Wirkung hat sie nur, wenn die Standard-Bedienelemente überhaupt angezeigt werden, also das Attribut controls gesetzt ist.

Unterstützt werden diese Token:

nodownload: blendet die Download-Schaltfläche aus
nofullscreen: blendet die Vollbild-Schaltfläche aus
noremoteplayback: blendet die Schaltfläche für die Remote-Wiedergabe (Cast) aus
noplaybackrate: blendet die Auswahl der Wiedergabegeschwindigkeit aus (Chrome 87+)

Die Eigenschaft ist nur lesbar, die Liste selbst kannst du aber mit den üblichen DOMTokenList-Methoden ändern, also add(), remove(), toggle(), contains() und supports(). Wenn du der Eigenschaft einen String zuweist, wird er an value weitergegeben und ersetzt den Attributwert. Nutze die Eigenschaft, wenn du die native Bedienleiste für einen bestimmten Zweck vereinfachen willst, ohne gleich eigene Bedienelemente zu bauen.

Rückgabewert

Typ

DOMTokenList

Beschreibung

Eine live aktualisierte DOMTokenList mit den Token aus dem Attribut controlslist. Ist das Attribut nicht gesetzt, ist die Liste leer.

Beispiele

Download- und Vollbild-Schaltfläche ausblenden

const video = document.querySelector('video');
video.controls = true;

// Steuerelemente ausblenden (nur wenn die Eigenschaft existiert)
if ('controlsList' in video) {
  video.controlsList.add('nodownload', 'nofullscreen');
}

console.log(video.controlsList.value);
console.log(video.getAttribute('controlslist'));

nodownload nofullscreen nodownload nofullscreen

Unterstützte Token per supports() prüfen

const audio = new Audio('podcast.mp3');
audio.controls = true;
document.body.append(audio);

const gewuenscht = ['nodownload', 'noplaybackrate', 'noremoteplayback'];

for (const token of gewuenscht) {
  if (audio.controlsList?.supports(token)) {
    audio.controlsList.add(token);
  } else {
    console.warn(`Token nicht unterstützt: ${token}`);
  }
}

console.log([...audio.controlsList]);

["nodownload", "noplaybackrate", "noremoteplayback"] // in Chrome 87+

Vollbild-Schaltfläche per Einstellung ein- und ausschalten

const video = document.querySelector('#lernvideo');
const checkbox = document.querySelector('#vollbild-erlauben');

checkbox.addEventListener('change', () => {
  // toggle(token, force): mit force=true hinzufügen, mit false entfernen
  video.controlsList.toggle('nofullscreen', !checkbox.checked);
  console.log('controlslist =', video.controlsList.value || '(leer)');
});

controlslist = nofullscreen controlslist = (leer)

Gesamte Liste per Zuweisung ersetzen

const video = document.querySelector('video');

// Die Zuweisung eines Strings setzt DOMTokenList.value
video.controlsList = 'nodownload noremoteplayback';
console.log(video.controlsList.contains('nodownload'));

video.controlsList = '';
console.log(video.controlsList.length);

true 0

// Wichtig · Fallstricke

Kompatibilität: controlsList ist nicht standardisiert (WICG-Vorschlag) und funktioniert nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari kennen die Eigenschaft nicht, dort ist sie undefined. Prüfe sie daher vorher, etwa mit 'controlsList' in element oder optionaler Verkettung (?.).

Kein Schutz vor Kopien: nodownload blendet nur die Schaltfläche aus. Die Mediendatei lässt sich weiterhin über die URL, die Entwicklerwerkzeuge oder das Kontextmenü (Rechtsklick → „Video speichern unter“) herunterladen. Für echten Schutz brauchst du serverseitige Maßnahmen oder DRM (Encrypted Media Extensions).

Weitere Fallstricke:

Ohne das Attribut controls hat die Eigenschaft keine sichtbare Wirkung.
nofullscreen entfernt nur die Schaltfläche. Ein Doppelklick auf das Video oder requestFullscreen() per Skript kann weiterhin in den Vollbildmodus schalten. Für einen vollständigen Ausschluss brauchst du zusätzlich disablePictureInPicture oder eine passende Permissions Policy.
Unbekannte Token lösen keinen Fehler aus, sie werden einfach ignoriert. Mit supports() kannst du vorher prüfen, ob ein Token bekannt ist.

Siehe auch

HTMLMediaElement.controller HTMLMediaElement.controls HTMLMediaElement.autoplay HTMLMediaElement.crossOrigin HTMLMediaElement.currentTime