Auf einem geteilten Tab scrollen und zoomen

François Beaufort
François Beaufort
GitHub
Elad Alon

Das Teilen von Tabs, Fenstern und Bildschirmen ist auf der Webplattform bereits mit der Screen Capture API möglich. Wenn eine Web-App getDisplayMedia() aufruft, fordert Chrome den Nutzer auf, einen Tab, ein Fenster oder einen Bildschirm als MediaStreamTrack-Video für die Web-App freizugeben.

Viele Web-Apps, die getDisplayMedia() verwenden, zeigen dem Nutzer eine Videovorschau der aufgenommenen Oberfläche. Videokonferenz-Apps streamen dieses Video beispielsweise häufig an Remote-Nutzer und rendern es gleichzeitig auf einem lokalen HTMLVideoElement, sodass der lokale Nutzer ständig eine Vorschau der Inhalte sieht, die er freigibt.

In dieser Dokumentation wird die neue Captured Surface Control API in Chrome vorgestellt, mit der Ihre Web-App einen erfassten Tab scrollen sowie die Zoomstufe eines erfassten Tabs lesen und schreiben kann.

Ein Nutzer scrollt und zoomt einen erfassten Tab (Demo).

Warum Captured Surface Control verwenden?

Alle Apps für Videokonferenzen haben denselben Nachteil. Wenn der Nutzer mit einem erfassten Tab oder Fenster interagieren möchte, muss er zu dieser Oberfläche wechseln, wodurch er die Videokonferenz-App verlässt. Das birgt einige Herausforderungen:

  • Der Nutzer kann die aufgezeichnete App und die Videostreams der Remote-Nutzer nicht gleichzeitig sehen, es sei denn, er verwendet Bild im Bild oder separate nebeneinander angeordnete Fenster für den Videokonferenztab und den freigegebenen Tab. Auf einem kleineren Bildschirm kann das schwierig sein.
  • Der Nutzer muss zwischen der Videokonferenz-App und der erfassten Oberfläche wechseln.
  • Der Nutzer verliert den Zugriff auf die Steuerelemente, die von der Videokonferenz-App bereitgestellt werden, wenn er sich nicht in der App befindet. Dazu gehören beispielsweise eine eingebettete Chat-App, Emoji-Reaktionen, Benachrichtigungen über Nutzer, die dem Anruf beitreten möchten, Multimedia- und Layout-Steuerelemente sowie andere nützliche Videokonferenzfunktionen.
  • Der Moderator kann die Steuerung nicht an Remote-Teilnehmer delegieren. Das führt zum allzu bekannten Szenario, in dem Remote-Nutzer den Referenten bitten, die Folie zu wechseln, ein wenig nach oben und unten zu scrollen oder den Zoomfaktor anzupassen.

Die Captured Surface Control API bietet eine Lösung für diese Probleme.

Wie verwende ich die Funktion „Aufgenommene Oberfläche steuern“?

Damit die Steuerung der erfassten Oberfläche funktioniert, sind einige Schritte erforderlich. So muss beispielsweise explizit ein Browser-Tab erfasst werden und der Nutzer muss die Berechtigung erteilen, bevor der erfasste Tab gescrollt und gezoomt werden kann.

Browsertab erfassen

Fordern Sie den Nutzer zuerst auf, eine Oberfläche auszuwählen, die er teilen möchte, indem Sie getDisplayMedia() verwenden. Ordnen Sie dabei ein CaptureController-Objekt der Aufnahmesitzung zu. Wir werden dieses Objekt bald verwenden, um die erfasste Oberfläche zu steuern.

const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });

Erstellen Sie als Nächstes eine lokale Vorschau der erfassten Oberfläche in Form eines <video>-Elements:

const previewTile = document.querySelector('video');
previewTile.srcObject = stream;

Wenn der Nutzer ein Fenster oder einen Bildschirm freigibt, ist das derzeit nicht möglich. Wenn er jedoch einen Tab freigibt, können wir fortfahren.

const [track] = stream.getVideoTracks();

if (track.getSettings().displaySurface !== 'browser') {
  // Bail out early if the user didn't pick a tab.
  return;
}

Berechtigungsaufforderung

Beim ersten Aufruf von forwardWheel(), increaseZoomLevel(), decreaseZoomLevel() oder resetZoomLevel() für ein bestimmtes CaptureController-Objekt wird eine Berechtigungsaufforderung angezeigt. Wenn der Nutzer die Berechtigung erteilt, sind weitere Aufrufe dieser Methoden zulässig.

Für die Anzeige einer Berechtigungsaufforderung für den Nutzer ist eine Nutzeraktion erforderlich. Die App sollte die oben genannten Methoden daher nur aufrufen, wenn sie entweder bereits die Berechtigung hat oder als Reaktion auf eine Nutzeraktion, z. B. einen click auf einer relevanten Schaltfläche in der Web-App.

Scrollen

Mit forwardWheel() kann eine Erfassungs-App Radereignisse von einem Quellelement in der Erfassungs-App selbst an den Viewport des erfassten Tabs weiterleiten. Diese Ereignisse sind für die erfasste App nicht von direkten Nutzerinteraktionen zu unterscheiden.

Angenommen, die Erfassungs-App verwendet ein <video>-Element namens "previewTile". Der folgende Code zeigt, wie Radereignisse an den erfassten Tab weitergeleitet werden:

const previewTile = document.querySelector('video');
try {
  // Relay the user's action to the captured tab.
  await controller.forwardWheel(previewTile);
} catch (error) {
  // Inspect the error.
  // ...
}

Die Methode forwardWheel() akzeptiert eine einzelne Eingabe, die eine der folgenden sein kann:

  • Ein HTML-Element, von dem aus Mausradereignisse an den erfassten Tab weitergeleitet werden.
  • null, was darauf hinweist, dass die Weiterleitung beendet werden soll.

Ein erfolgreicher Aufruf von forwardWheel() überschreibt vorherige Aufrufe.

Das von forwardWheel() zurückgegebene Promise kann in den folgenden Fällen abgelehnt werden:

  • Wenn die Aufzeichnungssitzung noch nicht gestartet wurde oder bereits beendet ist.
  • Wenn der Nutzer die entsprechende Berechtigung nicht erteilt hat.

Zoom

Die Interaktion mit dem Zoomfaktor des erfassten Tabs erfolgt über die folgenden CaptureController-API-Oberflächen:

getSupportedZoomLevels()

Diese Methode gibt eine Liste der Zoomstufen zurück, die vom Browser für den erfassten Oberflächentyp unterstützt werden. Die Werte in dieser Liste werden als Prozentsatz relativ zum „Standardzoomfaktor“ (100 %) dargestellt. Die Liste ist monoton steigend und enthält den Wert 100.

Diese Methode darf nur für unterstützte Typen von Anzeigeflächen aufgerufen werden. Derzeit sind das nur Tabs.

controller.getSupportedZoomLevels() kann aufgerufen werden, wenn die folgenden Bedingungen erfüllt sind:

  • controller ist mit einer aktiven Aufnahme verknüpft.
  • Die Aufnahme stammt von einem Tab.

Andernfalls wird ein Fehler ausgegeben.

Die Berechtigung "captured-surface-control" ist nicht erforderlich, um diese Methode aufzurufen.

zoomLevel

Dieses schreibgeschützte Attribut enthält die aktuelle Zoomstufe des erfassten Tabs. Es ist ein Attribut, das NULL-Werte zulässt, und enthält null, wenn der erfasste Oberflächentyp keine sinnvolle Definition der Zoomstufe hat. Derzeit ist die Zoomstufe nur für Tabs und nicht für Fenster oder Bildschirme definiert.

Nach dem Ende der Erfassung enthält das Attribut den letzten Zoomstufenwert.

Die Berechtigung "captured-surface-control" ist nicht erforderlich, um dieses Attribut zu lesen.

onzoomlevelchange

Mit diesem Ereignishandler können Sie auf Änderungen der Zoomstufe des erfassten Tabs reagieren. Diese können entweder:

  • Wenn der Nutzer mit dem Browser interagiert, um die Zoomstufe des erfassten Tabs manuell zu ändern.
  • Als Reaktion auf die Aufrufe der Zoom-Einstellungsmethoden (siehe unten) durch die Aufzeichnungs-App.

Die Berechtigung "captured-surface-control" ist nicht erforderlich, um dieses Attribut zu lesen.

increaseZoomLevel(), decreaseZoomLevel() und resetZoomLevel()

Mit diesen Methoden kann die Zoomstufe des erfassten Tabs geändert werden.

Mit increaseZoomLevel() und decreaseZoomLevel() wird die Zoomstufe auf die nächste bzw. vorherige Zoomstufe geändert, entsprechend der Reihenfolge, die von getSupportedZoomLevels() zurückgegeben wird. Mit resetZoomLevel() wird der Wert auf 100 festgelegt.

Die Berechtigung "captured-surface-control" ist erforderlich, um diese Methoden aufzurufen. Wenn die App, die die Aufnahme durchführt, diese Berechtigung nicht hat, wird der Nutzer aufgefordert, sie zu erteilen oder zu verweigern.

Alle diese Methoden geben ein Promise zurück, das aufgelöst wird, wenn der Aufruf erfolgreich ist, und andernfalls abgelehnt wird. Mögliche Gründe für eine Ablehnung:

  • Fehlende Berechtigung.
  • Wird vor dem Start der Aufnahme aufgerufen.
  • Wird nach dem Ende der Aufnahme aufgerufen.
  • Wird für ein controller aufgerufen, das mit einer Aufnahme eines nicht unterstützten Anzeigeflächentyps verknüpft ist. (Also alles außer Tab-Capture.)
  • Versuche, den Wert über den Höchstwert hinaus zu erhöhen oder unter den Mindestwert zu senken.

Es wird empfohlen, decreaseZoomLevel() nicht aufzurufen, wenn controller.zoomLevel == controller.getSupportedZoomLevels().at(0), und Aufrufe von increaseZoomLevel() auf ähnliche Weise mit .at(-1) zu schützen.

Im folgenden Beispiel wird gezeigt, wie der Nutzer die Zoomstufe eines erfassten Tabs direkt über die Erfassungs-App erhöhen kann:

const zoomIncreaseButton = document.getElementById('zoomInButton');
zoomIncreaseButton.addEventListener('click', async (event) => {
  if (controller.zoomLevel >= controller.getSupportedZoomLevels().at(-1)) {
    return;
  }
  try {
    await controller.increaseZoomLevel();
  } catch (error) {
    // Inspect the error.
    // ...
  }
});

Das folgende Beispiel zeigt, wie Sie auf Änderungen des Zoomfaktors eines erfassten Tabs reagieren:

controller.addEventListener('zoomlevelchange', (event) => {
  const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
  zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});

Funktionserkennung

So prüfen Sie, ob Captured Surface Control APIs unterstützt werden:

if (!!window.CaptureController?.prototype.forwardWheel) {
  // CaptureController forwardWheel() is supported.
}

Es ist auch möglich, eine der anderen Captured Surface Control API-Oberflächen wie increaseZoomLevel oder decreaseZoomLevel zu verwenden oder alle zu prüfen.

Unterstützte Browser

Die Funktion „Aufgenommene Oberfläche steuern“ ist nur auf Computern ab Chrome 136 verfügbar.

Sicherheit und Datenschutz

Mit der "captured-surface-control"-Berechtigungsrichtlinie können Sie verwalten, wie Ihre Erfassungs-App und eingebettete Drittanbieter-iFrames auf die Steuerung der erfassten Oberfläche zugreifen. Informationen zu den Sicherheitsrisiken finden Sie im Abschnitt Datenschutz- und Sicherheitsaspekte im Explainer zur Steuerung der erfassten Oberfläche.

Demo

Sie können mit Captured Surface Control experimentieren, indem Sie die Demo auf Glitch ausführen. Sehen Sie sich den Quellcode an.

Feedback

Das Chrome-Team und die Webstandards-Community möchten gern mehr über Ihre Erfahrungen mit der Funktion „Captured Surface Control“ erfahren.

Design beschreiben

Gibt es etwas an der Funktion „Captured Surface Capture“, das nicht wie erwartet funktioniert? Oder fehlen Methoden oder Eigenschaften, die Sie für die Umsetzung Ihrer Idee benötigen? Haben Sie eine Frage oder einen Kommentar zum Sicherheitsmodell? Melden Sie ein Spezifikationsproblem im GitHub-Repository oder fügen Sie einem bestehenden Problem Ihre Gedanken hinzu.

Probleme bei der Implementierung?

Haben Sie einen Fehler in der Chrome-Implementierung gefunden? Oder weicht die Implementierung von der Spezifikation ab? Melden Sie einen Fehler unter https://new.crbug.com. Geben Sie so viele Details wie möglich an und fügen Sie eine Anleitung zur Reproduktion hinzu.