CaptureController.resetZoomLevel() — Methode · JavaScript-Referenz

Signatur

CaptureController.prototype.resetZoomLevel()

Beschreibung

resetZoomLevel() gehört zur Captured Surface Control API. Mit dieser API kann eine Web-App, die per navigator.mediaDevices.getDisplayMedia() einen anderen Browser-Tab aufnimmt, diesen Tab fernsteuern. Die Methode setzt die Zoomstufe der aufgenommenen Fläche auf 100 (also 100 %) zurück. Das entspricht Strg+0 im aufgenommenen Tab.

Typischer Einsatz sind Videokonferenz- und Präsentations-Apps. Wer vortragen will, bleibt in der Konferenz-App, kann aber die geteilten Folien oder die Webseite vergrößern und über einen „Zoom zurücksetzen“-Knopf wieder auf Normalgröße bringen. Die Methode ergänzt increaseZoomLevel() und decreaseZoomLevel(). Die aktuelle Stufe steht in CaptureController.zoomLevel, die möglichen Stufen liefert getSupportedZoomLevels().

Voraussetzungen:

Der CaptureController wurde über die Option controller an getDisplayMedia() übergeben, und die Aufnahme läuft noch.
Die aufgenommene Fläche ist ein Browser-Tab. Bei Fenstern oder ganzen Bildschirmen funktioniert die Methode nicht.
Der Aufruf braucht eine vorübergehende Nutzeraktivierung (transient user activation), zum Beispiel einen Klick-Handler.
Die Berechtigung captured-surface-control wurde erteilt. Beim ersten Aufruf fragt der Browser danach.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Zoom zurückgesetzt ist. Abgelehnt wird es mit einer DOMException:

InvalidStateError: Der Controller gehört zu keiner laufenden Aufnahme, oder die Fläche ist kein Browser-Tab.
NotAllowedError: Es fehlt die Nutzeraktivierung, die Berechtigung wurde verweigert oder eine Permissions-Policy verbietet den Aufruf.

Beispiele

Tab-Aufnahme mit CaptureController starten und Zoom per Button zurücksetzen

const controller = new CaptureController();
const video = document.querySelector('#preview');
const resetBtn = document.querySelector('#zoom-reset');

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

// Der Aufruf muss direkt in einem Nutzer-Event erfolgen
resetBtn.addEventListener('click', async () => {
  try {
    await controller.resetZoomLevel();
    console.log('Zoom zurückgesetzt:', controller.zoomLevel);
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Zoom zurückgesetzt: 100

Vollständige Zoom-Steuerung mit Anzeige der aktuellen Stufe

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

const updateLabel = () => {
  label.textContent = `${controller.zoomLevel} %`;
};

// Löst aus, wenn sich der Zoom ändert – auch wenn der Nutzer im aufgenommenen Tab selbst zoomt
controller.addEventListener('zoomlevelchange', updateLabel);

const actions = {
  '#zoom-in': () => controller.increaseZoomLevel(),
  '#zoom-out': () => controller.decreaseZoomLevel(),
  '#zoom-reset': () => controller.resetZoomLevel()
};

for (const [selector, action] of Object.entries(actions)) {
  document.querySelector(selector).addEventListener('click', async () => {
    try {
      await action();
    } catch (err) {
      console.warn('Zoom-Steuerung fehlgeschlagen:', err.name);
    }
  });
}

document.querySelector('#share').addEventListener('click', async () => {
  await navigator.mediaDevices.getDisplayMedia({ video: true, controller });
  updateLabel();
});

Funktionserkennung und Reset-Button nur bei Tab-Aufnahme aktivieren

const supportsZoomControl =
  'CaptureController' in window &&
  'resetZoomLevel' in CaptureController.prototype;

const resetBtn = document.querySelector('#zoom-reset');
resetBtn.hidden = !supportsZoomControl;

if (supportsZoomControl) {
  const controller = new CaptureController();

  document.querySelector('#share').addEventListener('click', async () => {
    const stream = await navigator.mediaDevices.getDisplayMedia({ video: true, controller });
    const [track] = stream.getVideoTracks();
    // Zoom lässt sich nur bei Browser-Tabs steuern
    resetBtn.disabled = track.getSettings().displaySurface !== 'browser';
  });

  resetBtn.addEventListener('click', () => controller.resetZoomLevel());
}

// Wichtig · Fallstricke

Nutzeraktivierung ist Pflicht: Ohne vorherige Nutzerinteraktion wird das Promise mit NotAllowedError abgelehnt. Das gilt auch für Aufrufe aus einem Timer oder nach einem langen await, wenn die vorübergehende Aktivierung inzwischen abgelaufen ist.
Nur Browser-Tabs: Wird ein Fenster oder ein ganzer Bildschirm aufgenommen, schlägt der Aufruf mit InvalidStateError fehl. Das gilt auch, wenn die Aufnahme beendet oder der Tab geschlossen wurde. Prüfe deshalb track.getSettings().displaySurface.
Berechtigung und Permissions-Policy: Die Methode braucht die Berechtigung captured-surface-control. In iframes muss sie zusätzlich per allow="captured-surface-control" freigegeben sein.
Der Zoom wirkt auf den echten Tab: Das Zurücksetzen ändert den Zoom des aufgenommenen Tabs selbst, nicht nur das Aufnahmebild. Das bemerkt auch, wer diesen Tab gerade direkt benutzt.
Kompatibilität: Die Methode ist experimentell und bisher nur in Chromium-Browsern verfügbar (Chrome/Edge ab Version 136, davor als Origin Trial). Firefox und Safari unterstützen sie nicht, daher immer eine Funktionserkennung einbauen. Nur in sicheren Kontexten (HTTPS) verfügbar.

Siehe auch

CaptureController CaptureController.increaseZoomLevel() CaptureController.decreaseZoomLevel() CaptureController.zoomLevel CaptureController.getSupportedZoomLevels() CaptureController.forwardWheel() MediaDevices.getDisplayMedia()