CaptureController.getSupportedZoomLevels() — Methode · JavaScript-Referenz

Signatur

CaptureController.prototype.getSupportedZoomLevels()

Beschreibung

Die Methode getSupportedZoomLevels() gehört zur Captured Surface Control API. Mit ihr fragt eine Web-App, die einen anderen Browser-Tab per Bildschirmfreigabe aufnimmt, ab, welche Zoomstufen dieser Tab kennt. Rückgabewert ist ein Array von Zahlen, die Prozentwerte darstellen – 100 steht für 100 % (keine Vergrößerung), 50 für 50 %, 200 für 200 %.

Typischer Einsatz: Eine Videokonferenz-App zeigt eine freigegebene Präsentation und bietet eigene Zoom-Bedienelemente an, ohne dass der Nutzer zwischen den Tabs wechseln muss. Mit den gelieferten Stufen lässt sich z. B. eine Auswahlliste oder ein Schieberegler befüllen; der aktuelle Wert steht in CaptureController.zoomLevel, Änderungen erfolgen über increaseZoomLevel(), decreaseZoomLevel() und resetZoomLevel().

Die Methode funktioniert nur, wenn der CaptureController beim Aufruf von navigator.mediaDevices.getDisplayMedia() übergeben wurde, die Aufnahme aktiv ist und die erfasste Oberfläche ein Browser-Tab (displaySurface === "browser") ist. Fenster oder ganze Bildschirme lassen sich nicht zoomen.

Rückgabewert

Typ

number[]

Beschreibung

Aufsteigend sortiertes Array von Zoomstufen in Prozent, z. B. [25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500]. Die genauen Werte bestimmt der Browser.

Beispiele

Unterstützte Zoomstufen eines freigegebenen Tabs auslesen

const controller = new CaptureController();

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

  const [track] = stream.getVideoTracks();
  if (track.getSettings().displaySurface !== 'browser') {
    console.log('Zoom nur bei Browser-Tabs möglich.');
    return;
  }

  const levels = controller.getSupportedZoomLevels();
  console.log('Unterstützte Stufen:', levels);
  console.log('Aktuell:', controller.zoomLevel);
};

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

Unterstützte Stufen: [25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500] Aktuell: 100

Auswahlliste mit Zoomstufen befüllen und synchron halten

// Voraussetzung: controller wurde an getDisplayMedia() übergeben, Tab wird erfasst
const select = document.querySelector('#zoom');

const renderZoomOptions = (controller) => {
  select.replaceChildren(
    ...controller.getSupportedZoomLevels().map((level) => {
      const option = new Option(`${level} %`, level);
      option.selected = level === controller.zoomLevel;
      return option;
    })
  );
};

const setupZoomUI = (controller) => {
  renderZoomOptions(controller);
  // Zoom kann sich auch im erfassten Tab selbst ändern
  controller.addEventListener('zoomlevelchange', () => {
    select.value = controller.zoomLevel;
  });
};

Fehler robust abfangen und Unterstützung prüfen

const getZoomLevelsSafe = (controller) => {
  if (typeof controller?.getSupportedZoomLevels !== 'function') {
    console.warn('Captured Surface Control wird nicht unterstützt.');
    return [];
  }
  try {
    return controller.getSupportedZoomLevels();
  } catch (err) {
    // InvalidStateError: keine aktive Tab-Aufnahme
    console.warn(`${err.name}: ${err.message}`);
    return [];
  }
};

console.log(getZoomLevelsSafe(new CaptureController()));

InvalidStateError: ... []

// Wichtig · Fallstricke

InvalidStateError: wird ausgelöst, wenn der Controller noch nicht an eine Aufnahme gebunden ist, die Aufnahme beendet wurde oder die erfasste Oberfläche kein Browser-Tab ist (Fenster/Bildschirm).
Kompatibilität: experimentell und bislang nur in Chromium-basierten Desktop-Browsern verfügbar. Vor der Nutzung per Feature-Erkennung prüfen ('getSupportedZoomLevels' in CaptureController.prototype).
Berechtigungen: Die Captured Surface Control API unterliegt der Permissions Policy captured-surface-control. In iframes muss sie per allow-Attribut freigegeben werden. Anders als increaseZoomLevel() und Co. braucht das reine Auslesen der Stufen keine Nutzeraktivierung.
Die Liste nicht fest einprogrammieren – die Werte können je nach Browser und Version abweichen. Immer den Rückgabewert verwenden.
Nur in sicheren Kontexten (HTTPS) verfügbar.

Siehe auch

CaptureController.resetZoomLevel() CaptureController.decreaseZoomLevel() CaptureController.increaseZoomLevel() CaptureController.forwardWheel() CaptureController.setFocusBehavior()