CaptureController.decreaseZoomLevel() — Methode · JavaScript-Referenz

Signatur

CaptureController.prototype.decreaseZoomLevel()

Beschreibung

decreaseZoomLevel() gehört zur Captured Surface Control API. Die Methode verkleinert die Zoomstufe des Browser-Tabs, der über navigator.mediaDevices.getDisplayMedia() mit einem zugeordneten CaptureController erfasst wird, um eine Stufe. Die möglichen Stufen legt der Browser fest. Welche das sind, verrät getSupportedZoomLevels(), zum Beispiel [25, 33, 50, 67, 75, 80, 90, 100, 110, …].

Typischer Einsatz sind Videokonferenz- und Präsentationsanwendungen. Wer einen Tab teilt (etwa eine Foliensammlung), kann den Zoom direkt in der Konferenz-App anpassen und muss nicht zum geteilten Tab wechseln. Zusammen mit increaseZoomLevel(), resetZoomLevel(), der Eigenschaft zoomLevel und dem Ereignis zoomlevelchange lässt sich so eine vollständige Zoom-Steuerung bauen.

Die Methode ist nur unter diesen Bedingungen erlaubt:

Die erfasste Oberfläche ist ein Browser-Tab. Fenster und ganze Bildschirme werden nicht unterstützt.
Die Aufnahme läuft noch.
Der Aufruf geschieht mit vorübergehender Nutzeraktivierung, also zum Beispiel in einem click-Handler.
Die Berechtigung captured-surface-control ist erteilt. Beim ersten Aufruf fragt der Browser danach.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Zoomstufe verringert wurde. Wenn die Zoomstufe nicht verringert werden kann, wird das Promise mit einer DOMException abgelehnt (siehe Hinweise).

Beispiele

Tab erfassen und per Button herauszoomen

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

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

// Der Aufruf muss im Klick-Handler stehen (Nutzeraktivierung)
zoomOutBtn.addEventListener('click', async () => {
  try {
    await controller.decreaseZoomLevel();
    console.log(`Neue Zoomstufe: ${controller.zoomLevel} %`);
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Neue Zoomstufe: 90 %

Button bei minimaler Zoomstufe deaktivieren

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

const updateUi = () => {
  const levels = controller.getSupportedZoomLevels();
  const min = Math.min(...levels);
  label.textContent = `${controller.zoomLevel} %`;
  zoomOutBtn.disabled = controller.zoomLevel <= min;
};

// Wird bei jeder Zoomänderung ausgelöst, auch wenn der Nutzer direkt im Tab zoomt
controller.addEventListener('zoomlevelchange', updateUi);

zoomOutBtn.addEventListener('click', () => {
  controller.decreaseZoomLevel().catch((err) => console.warn(err.name));
});

Feature-Erkennung vor der Nutzung

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

document.querySelector('#zoom-controls').hidden = !supportsZoomControl;
console.log('Captured Surface Control verfügbar:', supportsZoomControl);

Captured Surface Control verfügbar: true

// Wichtig · Fallstricke

Mögliche Fehler (das Promise wird mit einer DOMException abgelehnt):

InvalidStateError: Der Controller ist noch keiner laufenden Aufnahme zugeordnet, die Aufnahme ist beendet, die erfasste Oberfläche ist kein Browser-Tab oder die kleinste Zoomstufe ist bereits erreicht.
NotAllowedError: Es fehlt die vorübergehende Nutzeraktivierung, der Nutzer hat die Berechtigung captured-surface-control verweigert oder eine Permissions Policy blockiert die Funktion.

Fallstricke:

Der CaptureController muss vor dem Aufruf an getDisplayMedia() übergeben werden. Ein Controller lässt sich nur für eine einzige Aufnahme verwenden.
Rufen Sie die Methode nicht in Timern oder nach längeren await-Ketten auf. Die Nutzeraktivierung läuft sonst ab.
Die Zoomstufe gilt für den erfassten Tab selbst. Der Nutzer sieht die Änderung also auch direkt in diesem Tab.

Kompatibilität: Die Funktion ist experimentell und bislang nur in Chromium-basierten Desktop-Browsern verfügbar. Firefox und Safari unterstützen sie nicht. Prüfen Sie die Unterstützung daher immer vorab (siehe Beispiel) und nutzen Sie die Methode nur in sicheren Kontexten (HTTPS).

Siehe auch

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