Blader en zoom op een vastgelegd tabblad.Scroll en zoom in op een vastgelegd tabblad

François Beaufort
François Beaufort
GitHub
Elad Alon

Het delen van tabbladen, vensters en schermen is al mogelijk op het webplatform met de Screen Capture API . Wanneer een webapp getDisplayMedia() aanroept, vraagt ​​Chrome de gebruiker om een ​​tabblad, venster of scherm met de webapp te delen als een MediaStreamTrack -video.

Veel webapps die getDisplayMedia() gebruiken, tonen de gebruiker een videopreview van het vastgelegde oppervlak. Videoconferentie-apps streamen deze video bijvoorbeeld vaak naar externe gebruikers en renderen deze tegelijkertijd naar een lokaal HTMLVideoElement , zodat de lokale gebruiker constant een preview ziet van wat hij of zij deelt.

In deze documentatie introduceren we de nieuwe Captured Surface Control API in Chrome, waarmee uw web-app een vastgelegd tabblad kan scrollen en het zoomniveau van een vastgelegd tabblad kan lezen en schrijven.

Een gebruiker scrolt en zoomt in op een vastgelegd tabblad ( demo ).

Waarom Captured Surface Control gebruiken?

Alle videoconferentie-apps hebben hetzelfde nadeel. Als de gebruiker een vastgelegd tabblad of venster wil gebruiken, moet hij of zij naar dat scherm overschakelen, waardoor de gebruiker de videoconferentie-app verlaat. Dit brengt enkele uitdagingen met zich mee:

  • De gebruiker kan de vastgelegde app en de videofeeds van externe gebruikers niet tegelijkertijd zien, tenzij hij Picture-in-Picture gebruikt of aparte vensters naast elkaar plaatst voor het tabblad Videoconferentie en het gedeelde tabblad. Op een kleiner scherm kan dit lastig zijn.
  • De gebruiker wordt belast met het feit dat hij steeds moet schakelen tussen de videoconferentie-app en het vastgelegde oppervlak.
  • De gebruiker verliest de toegang tot de bedieningselementen die de videoconferentie-app zichtbaar maakt wanneer hij of zij de app niet gebruikt, zoals een ingebedde chat-app, emoji-reacties, meldingen over gebruikers die willen deelnemen aan het gesprek, multimedia- en lay-outbedieningen en andere handige functies voor videoconferenties.
  • De presentator kan de controle niet delegeren aan deelnemers op afstand. Dit leidt tot het bekende scenario waarbij gebruikers op afstand de presentator vragen om de dia te wijzigen, een beetje omhoog en omlaag te scrollen of het zoomniveau aan te passen.

De Captured Surface Control API biedt een oplossing voor deze problemen.

Hoe gebruik ik Captured Surface Control?

Om Captured Surface Control succesvol te kunnen gebruiken, moet u een aantal stappen doorlopen. Zo moet u bijvoorbeeld expliciet een browsertabblad vastleggen en toestemming van de gebruiker krijgen voordat u op het vastgelegde tabblad kunt scrollen en zoomen.

Een browsertabblad vastleggen

Begin met het vragen aan de gebruiker om een ​​oppervlak te kiezen om te delen met behulp van getDisplayMedia() en koppel daarbij een CaptureController object aan de opnamesessie. We zullen dat object straks gebruiken om het opgenomen oppervlak te besturen.

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

Maak vervolgens een lokale preview van het vastgelegde oppervlak in de vorm van een <video> -element:

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

Als de gebruiker ervoor kiest om een ​​venster of scherm te delen, valt dat voorlopig buiten het bereik van de gebruiker. Als de gebruiker er echter voor kiest om een ​​tabblad te delen, kunnen we dat wel doen.

const [track] = stream.getVideoTracks();

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

Toestemmingsprompt

De eerste aanroep van forwardWheel() , increaseZoomLevel() , decreaseZoomLevel() of resetZoomLevel() op een bepaald CaptureController object genereert een toestemmingsprompt. Als de gebruiker toestemming verleent, zijn verdere aanroepen van deze methoden toegestaan.

Er is een gebruikersgebaar nodig om een ​​toestemmingsprompt aan de gebruiker te tonen. De app mag de bovengenoemde methoden dus alleen aanroepen als deze al over de toestemming beschikt, of als reactie op een gebruikersgebaar, zoals een click op een relevante knop in de web-app.

Rol

Met behulp van forwardWheel() kan een capture-app wielgebeurtenissen van een bronelement binnen de capture-app zelf doorsturen naar de viewport van het vastgelegde tabblad. Deze gebeurtenissen zijn voor de capture-app niet te onderscheiden van directe gebruikersinteractie.

Ervan uitgaande dat de opname-app een <video> -element met de naam "previewTile" gebruikt, laat de volgende code zien hoe u 'stuurwielgebeurtenissen' naar het vastgelegde tabblad kunt doorgeven:

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

De methode forwardWheel() accepteert één invoer, die een van de volgende kan zijn:

  • Een HTML-element waarvan wielgebeurtenissen worden doorgestuurd naar het vastgelegde tabblad.
  • null , wat aangeeft dat het doorsturen moet stoppen.

Een succesvolle aanroep van forwardWheel() overschrijft eerdere aanroepen.

De belofte die door forwardWheel() wordt geretourneerd, kan in de volgende gevallen worden afgewezen:

  • Als de opnamesessie nog niet is gestart of al is gestopt.
  • Als de gebruiker de relevante toestemming niet heeft verleend.

Zoom

Interactie met het zoomniveau van het vastgelegde tabblad gebeurt via de volgende CaptureController API-oppervlakken:

getSupportedZoomLevels()

Deze methode retourneert een lijst met zoomniveaus die door de browser worden ondersteund voor het vastgelegde oppervlaktype. De waarden in deze lijst worden weergegeven als een percentage ten opzichte van het standaard zoomniveau, dat is gedefinieerd als 100%. De lijst loopt monotoon op en bevat de waarde 100.

Deze methode kan alleen worden aangeroepen voor ondersteunde weergaveoppervlaktypen, wat op dit moment alleen voor tabbladen betekent.

controller.getSupportedZoomLevels() kan worden aangeroepen als aan de volgende voorwaarden wordt voldaan:

  • controller is gekoppeld aan een actieve vastlegging.
  • De opname is van een tabblad.

Anders wordt er een foutmelding gegenereerd.

De toestemming "captured-surface-control" is niet vereist om deze methode aan te roepen.

zoomLevel

Dit alleen-lezen kenmerk bevat het huidige zoomniveau van het vastgelegde tabblad. Het is een null-kenmerk en bevat null als het vastgelegde oppervlaktype geen betekenisvolle definitie van zoomniveau heeft. Momenteel is zoomniveau alleen gedefinieerd voor tabbladen en niet voor vensters of schermen.

Nadat de vastlegging is beëindigd, behoudt het kenmerk de laatste zoomwaarde.

De machtiging "captured-surface-control" is niet vereist om dit kenmerk te lezen.

onzoomlevelchange

Deze gebeurtenishandler maakt het mogelijk om te luisteren naar wijzigingen in het zoomniveau van het vastgelegde tabblad. Deze kunnen optreden:

  • Wanneer de gebruiker via de browser handmatig het zoomniveau van het vastgelegde tabblad wijzigt.
  • Als reactie op de oproepen van de opname-app naar de zoom-instellingsmethoden (hieronder beschreven).

De machtiging "captured-surface-control" is niet vereist om dit kenmerk te lezen.

increaseZoomLevel() , decreaseZoomLevel() en resetZoomLevel()

Met deze methoden kunt u het zoomniveau van het vastgelegde tabblad manipuleren.

increaseZoomLevel() en decreaseZoomLevel() wijzigen respectievelijk het zoomniveau naar het volgende of vorige zoomniveau, volgens de volgorde die wordt geretourneerd door getSupportedZoomLevels() . resetZoomLevel() stelt de waarde in op 100.

De machtiging "captured-surface-control" is vereist om deze methoden aan te roepen. Als de capture-app deze machtiging niet heeft, wordt de gebruiker gevraagd deze te verlenen of te weigeren.

Al deze methoden retourneren een belofte die wordt opgelost als de aanroep succesvol is en anders wordt afgewezen. Mogelijke oorzaken voor afwijzing zijn:

  • Toestemming ontbreekt.
  • Gebeld voordat de vangst begon.
  • Opgeroepen nadat de vangst was beëindigd.
  • Wordt aangeroepen op een controller die gekoppeld is aan een vastlegging van een niet-ondersteund weergaveoppervlaktype. (Dat wil zeggen, alles behalve tab-vastlegging.)
  • Probeert de waarde respectievelijk voorbij de maximum- of minimumwaarde te verhogen of te verlagen.

Het is met name aan te raden om het aanroepen van decreaseZoomLevel() te vermijden als controller.zoomLevel == controller.getSupportedZoomLevels().at(0) , en om aanroepen van increaseZoomLevel() op een vergelijkbare manier te beveiligen met .at(-1) .

Het volgende voorbeeld laat zien hoe de gebruiker het zoomniveau van een vastgelegd tabblad rechtstreeks vanuit de opname-app kan verhogen:

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.
    // ...
  }
});

Het volgende voorbeeld laat zien hoe u reageert op wijzigingen in het zoomniveau van een vastgelegd tabblad:

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

Functiedetectie

Om te controleren of Captured Surface Control API's worden ondersteund, gebruikt u:

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

Het is eveneens mogelijk om een ​​van de andere Captured Surface Control API-oppervlakken te gebruiken, zoals increaseZoomLevel of decreaseZoomLevel , of om zelfs op al deze oppervlakken te controleren.

Browserondersteuning

Captured Surface Control is alleen beschikbaar in Chrome 136 op desktop.

Beveiliging en privacy

Met het toestemmingsbeleid "captured-surface-control" kunt u beheren hoe uw capture-app en ingesloten iframes van derden toegang hebben tot Captured Surface Control. Raadpleeg het gedeelte Privacy- en beveiligingsoverwegingen van de uitleg over Captured Surface Control voor meer informatie over de beveiligingsaspecten.

Demonstratie

Je kunt Captured Surface Control spelen door de demo op Glitch te draaien. Bekijk zeker de broncode .

Feedback

Het Chrome-team en de webstandaardencommunity willen graag weten over uw ervaringen met Captured Surface Control.

Vertel ons over het ontwerp

Werkt Captured Surface Capture niet zoals verwacht? Of ontbreken er methoden of eigenschappen die je nodig hebt om je idee te implementeren? Heb je een vraag of opmerking over het beveiligingsmodel? Dien een spec-issue in op de GitHub-repository of voeg je mening toe aan een bestaand issue.

Probleem met de implementatie?

Heb je een bug gevonden in de implementatie van Chrome? Of wijkt de implementatie af van de specificatie? Meld een bug op https://new.crbug.com . Zorg ervoor dat je zoveel mogelijk details verstrekt, inclusief instructies voor reproductie.