CaptureController.forwardWheel() — Methode · JavaScript-Referenz

Signatur

CaptureController.prototype.forwardWheel(element)

Beschreibung

Die Methode forwardWheel() gehört zur Captured Surface Control API. Nach dem Aufruf werden Mausrad- und Touchpad-Scrollereignisse (wheel), die auf dem übergebenen Element auftreten, an den Viewport des aufgenommenen Tabs oder Fensters weitergeleitet. Nutzer können so in einer geteilten Präsentation, einem Dokument oder einer Webseite scrollen, ohne die eigene Videokonferenz-App zu verlassen.

Die Koordinaten des Ereignisses werden relativ zu den Abmessungen des Elements auf die aufgenommene Oberfläche umgerechnet. Deshalb sollte das Element die Vorschau der Aufnahme zeigen, typischerweise ein <video>-Element, dessen srcObject der von getDisplayMedia() gelieferte Stream ist. Mit null als Argument beenden Sie die Weiterleitung. Bei einem erneuten Aufruf mit einem anderen Element wird die Weiterleitung auf dieses Element umgestellt.

Voraussetzungen: Der CaptureController muss per getDisplayMedia({ controller }) an eine laufende Aufnahme gebunden sein, und die Aufnahme muss einen Tab oder ein Fenster betreffen. Beim ersten Aufruf fragt der Browser die Berechtigung captured-surface-control ab. Dafür ist eine vorübergehende Nutzeraktivierung nötig, der Aufruf muss also etwa in einem Klick-Handler stehen.

Parameter

Name	Typ	Default	Beschreibung
$element Pflicht	HTMLElement \| null		Das Element, dessen `wheel`-Ereignisse weitergeleitet werden sollen, meist das Vorschau-`<video>`. `null` beendet die Weiterleitung.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das sich mit undefined erfüllt, sobald die Weiterleitung eingerichtet (bzw. beendet) ist. Es wird mit einer DOMException abgelehnt, etwa NotAllowedError (Berechtigung verweigert oder keine Nutzeraktivierung), InvalidStateError (keine aktive Aufnahme oder Aufnahme bereits beendet) oder NotSupportedError (die Oberfläche lässt sich nicht steuern, z. B. ein ganzer Bildschirm oder der eigene Tab).

Beispiele

Tab teilen und Scrollen in der Vorschau aktivieren

const controller = new CaptureController();
const video = document.querySelector('#preview');
const startBtn = document.querySelector('#start');

startBtn.addEventListener('click', async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { displaySurface: 'browser' },
    controller
  });
  video.srcObject = stream;
  await video.play();
});

// Separater Klick, damit eine Nutzeraktivierung für die Berechtigung vorliegt
document.querySelector('#enable-scroll').addEventListener('click', async () => {
  try {
    await controller.forwardWheel(video);
    console.log('Scrollen wird an den geteilten Tab weitergeleitet');
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Scrollen wird an den geteilten Tab weitergeleitet

Weiterleitung per Umschalter ein- und ausschalten

const controller = new CaptureController();
const video = document.querySelector('#preview');
const toggle = document.querySelector('#scroll-toggle');
let forwarding = false;

toggle.addEventListener('click', async () => {
  try {
    await controller.forwardWheel(forwarding ? null : video);
    forwarding = !forwarding;
    toggle.textContent = forwarding ? 'Scrollen deaktivieren' : 'Scrollen aktivieren';
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      alert('Berechtigung zur Steuerung des geteilten Tabs wurde verweigert.');
    }
  }
});

Funktionserkennung und Berechtigungsstatus prüfen

const supportsForwardWheel =
  'CaptureController' in window &&
  'forwardWheel' in CaptureController.prototype;

if (supportsForwardWheel) {
  const status = await navigator.permissions.query({
    name: 'captured-surface-control'
  });
  console.log(`Berechtigung: ${status.state}`);
} else {
  console.log('Captured Surface Control wird nicht unterstützt');
}

Berechtigung: prompt

// Wichtig · Fallstricke

Experimentell: Die Methode ist bisher nur in Chromium-Browsern verfügbar (Chrome/Edge ab 136, davor als Origin Trial). Prüfen Sie die Unterstützung immer vorher mit 'forwardWheel' in CaptureController.prototype.
Nutzeraktivierung: Ruft man die Methode ohne vorübergehende Nutzeraktivierung auf (z. B. direkt nach dem Laden der Seite), wird das Promise mit NotAllowedError abgelehnt, solange die Berechtigung noch nicht erteilt ist.
Nur Tabs und Fenster: Bei der Aufnahme eines ganzen Bildschirms oder des eigenen Tabs schlägt der Aufruf fehl. Tipp: getDisplayMedia() mit displaySurface: 'browser' aufrufen.
Der CaptureController muss vor dem Aufruf von getDisplayMedia() übergeben werden. Jeder Controller lässt sich nur für eine einzige Aufnahme verwenden.
Die Weiterleitung endet automatisch, wenn die Aufnahme stoppt. Das Seitenverhältnis des Elements sollte dem des Videos entsprechen (z. B. object-fit beachten), sonst werden die Koordinaten falsch umgerechnet.
Sicherheit: Die API erlaubt, einen anderen Tab fernzusteuern. Der Browser zeigt deshalb eine Berechtigungsabfrage an, die per Permissions Policy captured-surface-control auch für iframes eingeschränkt werden kann.

Siehe auch

CaptureController CaptureController.increaseZoomLevel() CaptureController.decreaseZoomLevel() CaptureController.resetZoomLevel() CaptureController.zoomLevel MediaDevices.getDisplayMedia()