Auf einem geteilten Tab scrollen und zoomen

François Beaufort
François Beaufort
GitHub
Elad Alon

Mit der Screen Capture API ist es bereits möglich, Tabs, Fenster und Bildschirme auf der Webplattform zu teilen. Wenn eine Webanwendung getDisplayMedia() aufruft, wird der Nutzer von Chrome aufgefordert, einen Tab, ein Fenster oder einen Bildschirm als MediaStreamTrack-Video mit der Webanwendung zu teilen.

Viele Webanwendungen, die getDisplayMedia() verwenden, zeigen dem Nutzer eine Videovorschau der erfassten Oberfläche an. Beispielsweise wird dieses Video in Videokonferenz-Apps häufig an Remote-Nutzer gestreamt und gleichzeitig in einem lokalen HTMLVideoElement gerendert, damit der lokale Nutzer ständig eine Vorschau dessen sieht, was er teilt.

In dieser Dokumentation wird die neue Captured Surface Control API in Chrome vorgestellt. Mit dieser API kann Ihre Webanwendung einen erfassten Tab scrollen und die Zoomstufe eines erfassten Tabs lesen und schreiben.

Ein Nutzer scrollt und zoomt auf einem erfassten Tab (Demo).

Vorteile der Funktion „Captured Surface Control“

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

  • Der Nutzer kann die geteilte App und die Videofeeds der Remote-Nutzer nicht gleichzeitig sehen, es sei denn, er verwendet die Funktion Bild im Bild oder separate Fenster nebeneinander für den Tab „Videokonferenz“ und den Tab „Geteilt“. 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 der Videokonferenz-App, während er nicht aktiv ist. Dazu gehören beispielsweise eine eingebettete Chat-App, Emoji-Reaktionen, Benachrichtigungen über Nutzer, die am Anruf teilnehmen möchten, Multimedia- und Layoutsteuerungen sowie andere nützliche Funktionen für Videokonferenzen.
  • Der Vortragende kann die Kontrolle nicht an Remote-Teilnehmer delegieren. Das führt zu dem allzu bekannten Szenario, in dem Remote-Nutzer den Vortragenden bitten, die Folie zu wechseln, ein wenig nach oben und unten zu scrollen oder den Zoomfaktor anzupassen.

Die Captured Surface Control API löst diese Probleme.

Wie verwende ich die Funktion „Captured Surface Control“?

Die Verwendung der Funktion „Gecapturte Oberfläche steuern“ erfordert einige Schritte. So müssen Sie beispielsweise einen Browsertab explizit erfassen und die Berechtigung des Nutzers einholen, bevor Sie den erfassten Tab scrollen und zoomen können.

Browsertab erfassen

Bitten Sie den Nutzer zuerst, eine Oberfläche auszuwählen, die er mit getDisplayMedia() teilen möchte, und ordnen Sie der Aufnahmesitzung ein CaptureController-Objekt zu. Dieses Objekt wird bald verwendet, 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;
}

Berechtigungsanfrage

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

Damit dem Nutzer eine Berechtigungsanfrage angezeigt werden kann, 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. ein click auf einer relevanten Schaltfläche in der Webanwendung.

Scrollen

Mit forwardWheel() kann eine Aufnahme-App Rad-Ereignisse von einem Quellelement innerhalb der Aufnahme-App an den Viewport des aufgenommenen Tabs weiterleiten. Diese Ereignisse sind für die erfasste App nicht von einer direkten Nutzerinteraktion zu unterscheiden.

Angenommen, die App für die Aufnahme verwendet ein <video>-Element namens "previewTile". Im folgenden Code wird gezeigt, wie Sie Sende-Rad-Ereignisse an den Tab weiterleiten, der aufgenommen wird:

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() nimmt eine einzelne Eingabe an, die Folgendes sein kann:

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

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

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

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

Zoom

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

getSupportedZoomLevels()

Diese Methode gibt eine Liste der vom Browser unterstützten Zoomstufen für den erfassten Oberflächentyp zurück. Die Werte in dieser Liste werden als Prozentsatz im Vergleich zur „Standardzoomstufe“ dargestellt, die als 100 % definiert ist. Die Liste ist monoton steigend und enthält den Wert 100.

Diese Methode darf nur für unterstützte Bildschirmoberflächentypen aufgerufen werden, derzeit also nur für Tabs.

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

  • controller ist mit einer aktiven Aufnahme verknüpft.
  • Die Aufnahme zeigt einen Tab.

Andernfalls wird ein Fehler ausgegeben.

Die Berechtigung "captured-surface-control" ist für den Aufruf dieser Methode nicht erforderlich.

zoomLevel

Dieses schreibgeschützte Attribut enthält die aktuelle Zoomstufe des erfassten Tabs. Es ist ein Nullable-Attribut und enthält null, wenn für den erfassten Oberflächentyp keine sinnvolle Definition der Zoomstufe vorhanden ist. Derzeit ist die Zoomstufe nur für Tabs und nicht für Fenster oder Bildschirme definiert.

Nach Abschluss der Aufnahme enthält das Attribut den letzten Wert der Zoomstufe.

Die Berechtigung "captured-surface-control" ist nicht für das Lesen dieses Attributs erforderlich.

onzoomlevelchange

Mit diesem Ereignishandler können Sie Änderungen an der Zoomstufe des erfassten Tabs überwachen. Das kann entweder passieren:

  • Wenn der Nutzer mit dem Browser interagiert, um die Zoomstufe des erfassten Tabs manuell zu ändern.
  • Als Reaktion auf Aufrufe der Aufnahme-App an die Methoden für die Zoomeinstellungen (siehe unten).

Die Berechtigung "captured-surface-control" ist nicht für das Lesen dieses Attributs erforderlich.

increaseZoomLevel(), decreaseZoomLevel() und resetZoomLevel()

Mit diesen Methoden lässt sich die Zoomstufe des erfassten Tabs manipulieren.

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

Die Berechtigung "captured-surface-control" ist für den Aufruf dieser Methoden erforderlich. Wenn die App, mit der die Aufnahme erfolgt, diese Berechtigung nicht hat, wird der Nutzer aufgefordert, sie zu gewähren oder abzulehnen.

Diese Methoden geben alle ein Versprechen zurück, das bei Erfolg erfüllt und andernfalls abgelehnt wird. Mögliche Gründe für eine Ablehnung:

  • Fehlende Berechtigung.
  • Wird aufgerufen, bevor die Aufnahme gestartet wird.
  • Wird nach dem Ende der Aufnahme aufgerufen.
  • Wird für eine controller aufgerufen, die mit einer Aufnahme eines nicht unterstützten Displayoberflächentyps verknüpft ist. (Das heißt, alles außer Tab-Aufzeichnungen.)
  • Es wird versucht, den Wert über den Höchst- bzw. unter den Mindestwert zu erhöhen oder zu senken.

Insbesondere 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 den Zoom eines erfassten Tabs direkt über die App für die Erfassung 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.
    // ...
  }
});

Im folgenden Beispiel wird gezeigt, wie auf Änderungen der Zoomebene eines erfassten Tabs reagiert wird:

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

Funktionserkennung

So prüfen Sie, ob APIs für die Steuerung von erfassten Oberflächen unterstützt werden:

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

Sie können auch eine der anderen APIs für die Steuerung der erfassten Oberfläche verwenden, z. B. increaseZoomLevel oder decreaseZoomLevel, oder sogar nach allen suchen.

Unterstützte Browser

Die Funktion „Gesteuerte Oberfläche“ ist ab Chrome 136 nur auf dem Computer verfügbar.

Sicherheit und Datenschutz

Mit der "captured-surface-control" Berechtigungsrichtlinie können Sie festlegen, wie Ihre App zum Erfassen von Inhalten und eingebettete Iframes von Drittanbietern auf die Steuerelemente für erfasste Oberflächen zugreifen. Weitere Informationen zu den Sicherheitsabwägungen finden Sie im Abschnitt Datenschutz- und Sicherheitsaspekte der Erläuterung zur Funktion „Gescannte Oberfläche steuern“.

Demo

Sie können die Funktion „Captured Surface Control“ ausprobieren, indem Sie die Demo auf Glitch ausführen. Sehen Sie sich den Quellcode an.

Feedback

Das Chrome-Team und die Webstandards-Community möchten von Ihnen wissen, welche Erfahrungen Sie mit der Funktion „Captured Surface Control“ gemacht haben.

Designbeschreibung

Funktioniert die Funktion „Aufgenommene Oberfläche erfassen“ nicht wie erwartet? Oder fehlen Methoden oder Eigenschaften, die Sie für die Implementierung Ihrer Idee benötigen? Haben Sie Fragen oder Kommentare zum Sicherheitsmodell? Melden Sie ein Problem mit der Spezifikation im GitHub-Repository oder fügen Sie Ihre Gedanken zu einem vorhandenen Problem hinzu.

Problem bei der Implementierung?

Haben Sie einen Fehler in der Chrome-Implementierung gefunden? Oder unterscheidet sich die Implementierung von der Spezifikation? Melden Sie den Fehler unter https://new.crbug.com. Geben Sie dabei so viele Details wie möglich an und geben Sie eine Anleitung zur Reproduktion an. Glitch eignet sich hervorragend, um reproduzierbare Fehler zu teilen.