CaptureController.increaseZoomLevel() — Methode · JavaScript-Referenz

Signatur

CaptureController.prototype.increaseZoomLevel()

Beschreibung

Die Methode increaseZoomLevel() gehört zur Captured Surface Control API. Mit ihr kann eine Web-Anwendung, die per navigator.mediaDevices.getDisplayMedia() einen anderen Browser-Tab aufnimmt, dessen Zoomstufe direkt aus der eigenen Oberfläche heraus erhöhen. Der Nutzer muss also nicht zum erfassten Tab wechseln, um die Darstellung zu vergrößern. Das ist z. B. in Videokonferenz-Apps nützlich, in denen eine Präsentation geteilt wird und die Vortragende den Inhalt für die Zuschauer größer darstellen möchte.

Der Zoom wird um genau einen Schritt auf die nächsthöhere der vom Browser unterstützten Stufen gesetzt. Welche Stufen es gibt, liefert CaptureController.getSupportedZoomLevels(), die aktuelle Stufe steht in CaptureController.zoomLevel (in Prozent, z. B. 100). Jede Änderung, auch eine durch den Nutzer im erfassten Tab ausgelöste, meldet das Ereignis zoomlevelchange.

Voraussetzungen für einen erfolgreichen Aufruf:

Der CaptureController wurde beim Aufruf von getDisplayMedia({ controller }) übergeben, und die Aufnahme läuft noch.
Die erfasste Oberfläche ist ein Browser-Tab (displaySurface: "browser"), kein Fenster und kein Bildschirm.
Der Aufruf erfolgt mit vorübergehender Nutzeraktivierung (z. B. innerhalb eines click-Handlers).
Die Berechtigung "captured-surface-control" wurde erteilt (der Browser fragt beim ersten Aufruf nach), und die Permissions-Policy erlaubt sie.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Zoomstufe erhöht wurde. Es wird z. B. mit InvalidStateError abgelehnt, wenn keine Tab-Aufnahme aktiv ist oder die höchste Stufe schon erreicht ist, und mit NotAllowedError, wenn Nutzeraktivierung oder Berechtigung fehlen.

Beispiele

Tab aufnehmen und per Button hineinzoomen

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

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

// Aufruf innerhalb eines Klick-Handlers = Nutzeraktivierung vorhanden
zoomInBtn.addEventListener('click', async () => {
  try {
    await controller.increaseZoomLevel();
    console.log(`Neue Zoomstufe: ${controller.zoomLevel}%`);
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Neue Zoomstufe: 110%

Zoom-Anzeige über das zoomlevelchange-Ereignis aktualisieren

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

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

// Reagiert auch auf Zoom-Änderungen, die der Nutzer direkt im Tab vornimmt
controller.addEventListener('zoomlevelchange', updateLabel);
// Alternativ: controller.onzoomlevelchange = updateLabel;

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

100 %

Button bei maximaler Zoomstufe deaktivieren

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

const refreshButton = () => {
  const levels = controller.getSupportedZoomLevels();
  const max = Math.max(...levels);
  zoomInBtn.disabled = controller.zoomLevel >= max;
};

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

if (track.getSettings().displaySurface === 'browser') {
  refreshButton();
  controller.addEventListener('zoomlevelchange', refreshButton);
  zoomInBtn.addEventListener('click', () => controller.increaseZoomLevel());
} else {
  // Zoom-Steuerung funktioniert nur bei Tabs
  zoomInBtn.hidden = true;
}

Feature-Erkennung

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

console.log(supportsZoomControl ? 'Zoom-Steuerung verfügbar' : 'Nicht unterstützt');

Zoom-Steuerung verfügbar

// Wichtig · Fallstricke

Nur Browser-Tabs: Bei Aufnahme eines Fensters oder des gesamten Bildschirms wird das Promise abgelehnt. Prüfen Sie vorher track.getSettings().displaySurface === "browser".
Nutzeraktivierung erforderlich: Aufrufe aus Timern, nach längeren await-Ketten oder ohne Nutzerinteraktion schlagen mit NotAllowedError fehl.
Berechtigung: Beim ersten Aufruf fragt der Browser nach der Berechtigung "captured-surface-control". In iframes muss die Permissions-Policy diese Berechtigung freigeben (allow="captured-surface-control").
Obergrenze: Ist die höchste Stufe aus getSupportedZoomLevels() erreicht, lässt sich nicht weiter zoomen. Deaktivieren Sie den Button daher rechtzeitig, statt auf Fehler zu warten.
Zoom gilt für den Tab selbst: Der Zoom wird im erfassten Tab tatsächlich geändert, nicht nur im Videostream. Das sieht also auch jemand, der direkt auf den Tab schaut.
Kompatibilität: Die Funktion ist experimentell und bisher nur in Chromium-basierten Desktop-Browsern verfügbar. Firefox, Safari und mobile Browser unterstützen sie nicht, deshalb immer eine Feature-Erkennung einbauen.

Siehe auch

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