Signatur
Beschreibung
zoomLevel gehört zur Captured Surface Control API. Sie erweitert das Interface CaptureController, das man über die Option controller an navigator.mediaDevices.getDisplayMedia() übergibt. Über die Eigenschaft liest eine Anwendung den aktuellen Zoomfaktor des erfassten Tabs aus, also nicht den der eigenen Seite. Der Wert ist eine ganze Zahl in Prozent, zum Beispiel 100, 125 oder 67.
Typischer Einsatz sind Videokonferenz- und Präsentations-Apps. Man teilt einen Tab, etwa mit Folien, und möchte dessen Zoom direkt aus der eigenen Oberfläche steuern, ohne zum geteilten Tab zu wechseln. zoomLevel zeigt dabei den aktuellen Wert an, zum Beispiel in einer Beschriftung wie „125 %“. Geändert wird der Zoom über increaseZoomLevel(), decreaseZoomLevel() und resetZoomLevel(). Welche Stufen es gibt, liefert getSupportedZoomLevels().
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wie controller.zoomLevel = 150 ändert nichts. Der Zoom kann sich auch ändern, wenn Nutzer im erfassten Tab selbst zoomen, zum Beispiel mit Strg + Mausrad. Deshalb sollte man auf das Ereignis zoomlevelchange hören und die Anzeige dort aktualisieren, statt den Wert nur einmal auszulesen.
Rückgabewert
100. Der Wert entspricht immer einem Eintrag aus getSupportedZoomLevels().Beispiele
Tab erfassen und Zoomfaktor auslesen
const controller = new CaptureController();
const startCapture = async () => {
const stream = await navigator.mediaDevices.getDisplayMedia({
video: true,
controller,
preferCurrentTab: false
});
const [track] = stream.getVideoTracks();
// Zoom lässt sich nur bei Browser-Tabs steuern
if (track.getSettings().displaySurface !== 'browser') {
console.log('Kein Tab erfasst – Zoom-Steuerung nicht verfügbar.');
return;
}
console.log(`Aktueller Zoom: ${controller.zoomLevel} %`);
};
document.querySelector('#share').addEventListener('click', startCapture);Zoom-Anzeige mit Plus-/Minus-Schaltflächen synchron halten
const controller = new CaptureController();
const label = document.querySelector('#zoom-label');
const updateLabel = () => {
label.textContent = `${controller.zoomLevel} %`;
};
// Wird auch ausgelöst, wenn Nutzer direkt im erfassten Tab zoomen
controller.addEventListener('zoomlevelchange', updateLabel);
document.querySelector('#zoom-in').addEventListener('click', async () => {
try {
await controller.increaseZoomLevel(); // braucht eine Nutzeraktion
} catch (err) {
console.warn('Zoom nicht möglich:', err.name);
}
});
document.querySelector('#zoom-out').addEventListener('click', () =>
controller.decreaseZoomLevel().catch((err) => console.warn(err.name))
);
document.querySelector('#share').addEventListener('click', async () => {
await navigator.mediaDevices.getDisplayMedia({ video: true, controller });
updateLabel();
});Grenzen erkennen und Schaltflächen deaktivieren
const updateButtons = (controller) => {
const levels = controller.getSupportedZoomLevels();
const current = controller.zoomLevel;
document.querySelector('#zoom-out').disabled = current === levels[0];
document.querySelector('#zoom-in').disabled = current === levels.at(-1);
document.querySelector('#zoom-reset').disabled = current === 100;
console.log(`Zoom ${current} % (Bereich ${levels[0]}–${levels.at(-1)} %)`);
};// Wichtig · Fallstricke
- Browserunterstützung: Die API ist experimentell. Bisher gibt es sie nur in Chromium-basierten Browsern auf dem Desktop, nicht in Firefox und nicht in Safari. Deshalb vorher die Unterstützung prüfen, z. B. mit
'zoomLevel' in CaptureController.prototype. - Nur Browser-Tabs: Wird ein Fenster oder der ganze Bildschirm geteilt, gibt es keinen steuerbaren Zoom. Dasselbe gilt vor dem Start und nach dem Ende der Erfassung. Der Zugriff liefert dann keinen sinnvollen Wert oder löst je nach Implementierung einen Fehler aus (
InvalidStateError). Deshalb vorhertrack.getSettings().displaySurface === 'browser'prüfen. - Schreibgeschützt: Eine Zuweisung wird still ignoriert. Zum Ändern dienen
increaseZoomLevel(),decreaseZoomLevel()undresetZoomLevel(). Diese Methoden brauchen eine vorübergehende Nutzeraktion (transient user activation), also z. B. einen Klick. - Berechtigung: Die Steuerung kann durch die Permissions Policy
captured-surface-controleingeschränkt sein. Außerdem fragt der Browser die Nutzer gegebenenfalls einmal um Erlaubnis. - Der Wert ist kein Faktor wie
1.25, sondern eine Prozentzahl wie125. Er sagt nichts überdevicePixelRatiooder den Zoom der eigenen Seite aus.