RemotePlayback.cancelWatchAvailability() — Methode · JavaScript-Referenz

Signatur

RemotePlayback.prototype.cancelWatchAvailability(id)

Beschreibung

Mit cancelWatchAvailability() meldest du Callbacks ab, die du vorher mit RemotePlayback.watchAvailability() registriert hast. Solche Callbacks sagen dir, ob gerade externe Wiedergabegeräte wie Chromecast, AirPlay-Empfänger oder Smart-TVs erreichbar sind. So kannst du z. B. einen „Auf Fernseher abspielen“-Button ein- oder ausblenden.

Übergibst du die id, die das Promise von watchAvailability() geliefert hat, wird nur dieser eine Callback entfernt. Ohne Argument werden alle Verfügbarkeits-Callbacks des jeweiligen RemotePlayback-Objekts abgemeldet.

Die Geräteerkennung im Hintergrund braucht Energie und Netzwerkressourcen. Browser sollen sie nur laufen lassen, solange mindestens ein Callback registriert ist. Melde Callbacks deshalb ab, sobald du sie nicht mehr brauchst: zum Beispiel wenn das Video-Element entfernt wird, die Komponente ausgehängt wird oder Remote-Wiedergabe aus einem anderen Grund nicht mehr angeboten wird.

Parameter

Name	Typ	Default	Beschreibung
$id	number		Kennung eines Callbacks. Du bekommst sie, wenn das Promise von `watchAvailability()` erfüllt wird. Lässt du sie weg, werden alle Callbacks entfernt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Callback bzw. alle Callbacks abgemeldet sind. Es wird mit einer DOMException abgelehnt, wenn die Abmeldung nicht möglich ist (siehe Hinweise).

Beispiele

Einzelnen Callback per ID abmelden

const video = document.querySelector('video');
const castButton = document.querySelector('#cast-button');

const onAvailability = (available) => {
  castButton.hidden = !available;
};

const start = async () => {
  try {
    const id = await video.remote.watchAvailability(onAvailability);
    console.log('Überwachung aktiv, ID:', id);

    // Nach 30 Sekunden nicht mehr überwachen
    setTimeout(async () => {
      await video.remote.cancelWatchAvailability(id);
      console.log('Überwachung beendet');
    }, 30_000);
  } catch (err) {
    console.warn('Verfügbarkeit nicht überwachbar:', err.name);
  }
};

start();

Überwachung aktiv, ID: 1 Überwachung beendet

Alle Callbacks beim Entfernen des Players abmelden

const cleanupPlayer = async (video) => {
  if (!('remote' in video)) return;
  try {
    // Ohne Argument: alle Callbacks dieses Elements entfernen
    await video.remote.cancelWatchAvailability();
    console.log('Alle Verfügbarkeits-Callbacks entfernt');
  } catch (err) {
    console.warn('Abmeldung fehlgeschlagen:', err.name);
  } finally {
    video.remove();
  }
};

cleanupPlayer(document.querySelector('video'));

Alle Verfügbarkeits-Callbacks entfernt

Fehlerfälle gezielt behandeln

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

const safeCancel = async (id) => {
  try {
    await video.remote.cancelWatchAvailability(id);
  } catch (err) {
    if (err.name === 'NotFoundError') {
      console.info(`Kein Callback mit ID ${id} registriert`);
    } else if (err.name === 'InvalidStateError') {
      console.info('Remote-Wiedergabe ist deaktiviert (disableRemotePlayback)');
    } else {
      throw err;
    }
  }
};

safeCancel(42);

Kein Callback mit ID 42 registriert

// Wichtig · Fallstricke

InvalidStateError: Das Promise wird abgelehnt, wenn am Medienelement disableRemotePlayback gesetzt ist.
NotFoundError: Das Promise wird abgelehnt, wenn für die übergebene id kein Callback registriert ist, etwa weil er schon entfernt wurde.
Die IDs gelten nur für das jeweilige RemotePlayback-Objekt, also für ein bestimmtes Medienelement. Eine ID von videoA.remote funktioniert nicht bei videoB.remote.
Ohne Argument werden auch Callbacks entfernt, die andere Teile deines Codes registriert haben. In größeren Anwendungen ist es daher meist besser, gezielt per ID abzumelden.
Browser-Unterstützung: Safari (macOS/iOS, AirPlay) und Chrome für Android. Firefox unterstützt die API nicht. Chrome auf dem Desktop lehnt watchAvailability() teilweise mit NotSupportedError ab. Prüfe vorher mit 'remote' in HTMLMediaElement.prototype, ob die API vorhanden ist.

Siehe auch

RemotePlayback RemotePlayback.watchAvailability() RemotePlayback.prompt() RemotePlayback.state HTMLMediaElement.remote HTMLMediaElement.disableRemotePlayback