CaptureController: zoomlevelchange — Ereignis · JavaScript-Referenz

Signatur

captureController.addEventListener("zoomlevelchange", handler)

Beschreibung

Das Ereignis zoomlevelchange gehört zur Captured Surface Control API. Es wird an einem CaptureController ausgelöst, sobald sich der Zoom-Level der mit navigator.mediaDevices.getDisplayMedia() aufgenommenen Oberfläche ändert – egal ob die Änderung durch die aufnehmende Anwendung selbst (increaseZoomLevel(), decreaseZoomLevel(), resetZoomLevel()) oder durch den Nutzer direkt im aufgenommenen Tab (z. B. Strg + +) ausgelöst wurde.

Typischer Einsatzzweck sind Videokonferenz- oder Präsentations-Apps, die einen geteilten Tab fernsteuern: Über das Ereignis lässt sich eine eigene Zoom-Anzeige (etwa „125 %“) aktuell halten oder Schaltflächen deaktivieren, wenn der minimale bzw. maximale Wert aus getSupportedZoomLevels() erreicht ist. Den aktuellen Wert liest man im Handler über die Eigenschaft captureController.zoomLevel aus.

Der Handler kann entweder per addEventListener("zoomlevelchange", handler) oder über die Eigenschaft onzoomlevelchange registriert werden. Das übergebene Objekt ist ein einfaches Event ohne zusätzliche Eigenschaften; es ist nicht abbrechbar und steigt nicht auf (bubbles).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"zoomlevelchange"`.
$handler Pflicht	(event: Event) => void		Callback, das bei jeder Zoom-Änderung aufgerufen wird. Erhält ein generisches `Event`; den neuen Wert liefert `event.target.zoomLevel`.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Das Ereignisobjekt ist ein Event; der aktuelle Zoom-Level (Prozentwert, z. B. 100) steht in CaptureController.zoomLevel.

Beispiele

Zoom-Anzeige beim Teilen eines Tabs aktuell halten

const controller = new CaptureController();
const zoomLabel = document.querySelector('#zoom-label');

controller.addEventListener('zoomlevelchange', () => {
  // zoomLevel ist ein Prozentwert, z. B. 110
  zoomLabel.textContent = `${controller.zoomLevel} %`;
  console.log('Neuer Zoom-Level:', controller.zoomLevel);
});

const startSharing = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { displaySurface: 'browser' },
    controller
  });
  document.querySelector('video').srcObject = stream;
};

document.querySelector('#share').addEventListener('click', startSharing);

Neuer Zoom-Level: 110

Zoom-Buttons mit on-Property und Grenzwerten steuern

const controller = new CaptureController();
const btnPlus = document.querySelector('#zoom-in');
const btnMinus = document.querySelector('#zoom-out');

const updateButtons = () => {
  const levels = controller.getSupportedZoomLevels();
  btnPlus.disabled = controller.zoomLevel >= levels.at(-1);
  btnMinus.disabled = controller.zoomLevel <= levels[0];
};

// Alternative zur addEventListener-Variante
controller.onzoomlevelchange = updateButtons;

// Zoom-Änderungen benötigen eine Nutzeraktivierung (Klick)
btnPlus.addEventListener('click', () => controller.increaseZoomLevel());
btnMinus.addEventListener('click', () => controller.decreaseZoomLevel());

await navigator.mediaDevices.getDisplayMedia({ video: true, controller });
updateButtons();

Listener per AbortSignal wieder entfernen

const controller = new CaptureController();
const listenerAbort = new AbortController();

controller.addEventListener(
  'zoomlevelchange',
  () => console.log('Zoom:', controller.zoomLevel),
  { signal: listenerAbort.signal }
);

const stream = await navigator.mediaDevices.getDisplayMedia({ video: true, controller });

// Beim Beenden der Aufnahme Listener aufräumen
stream.getVideoTracks()[0].addEventListener('ended', () => {
  listenerAbort.abort();
  controller.onzoomlevelchange = null;
});

Zoom: 90

// Wichtig · Fallstricke

Experimentell: Die Captured Surface Control API gibt es bisher nur in Chromium-basierten Browsern (Chrome/Edge ab Version 136, vorher als Origin Trial). Firefox und Safari unterstützen sie nicht – vorher mit 'onzoomlevelchange' in CaptureController.prototype prüfen.
Das Ereignis wird nur ausgelöst, wenn ein Browser-Tab aufgenommen wird (displaySurface: \"browser\"). Bei Fenstern oder ganzen Bildschirmen kommt kein Ereignis; zoomLevel ist dann null bzw. die Methoden werfen einen Fehler.
Der CaptureController muss vor dem Aufruf an getDisplayMedia() übergeben werden; ein Controller ist nur für eine einzige Aufnahme verwendbar.
increaseZoomLevel() und Co. erfordern eine vorübergehende Nutzeraktivierung sowie die Berechtigung \"captured-surface-control\" (auch per Permissions-Policy steuerbar). Das Ereignis selbst feuert aber auch bei Zoom-Änderungen durch den Nutzer im geteilten Tab.
Das Ereignis enthält keinen neuen Wert – immer controller.zoomLevel auslesen.

Siehe auch

BatteryManager: levelchange WindowControlsOverlay: geometrychange BatteryManager: chargingchange ServiceWorker: statechange VirtualKeyboard: geometrychange