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 videovoorbeeld van het vastgelegde oppervlak. Apps voor videoconferenties streamen deze video bijvoorbeeld vaak naar externe gebruikers en renderen deze ook naar een lokaal HTMLVideoElement , zodat de lokale gebruiker voortdurend een voorbeeld ziet van wat hij deelt.
Deze documentatie introduceert de nieuwe Captured Surface Control API in Chrome, waarmee uw webapp door een vastgelegd tabblad kan scrollen en het zoomniveau van een vastgelegd tabblad kan lezen en schrijven.
Waarom Captured Surface Control gebruiken?
Alle apps voor videoconferenties hebben hetzelfde nadeel. Als de gebruiker wil communiceren met een vastgelegd tabblad of venster, moet de gebruiker naar dat oppervlak overschakelen en deze weghalen uit de videoconferentie-app. Dit brengt enkele uitdagingen met zich mee:
- De gebruiker kan de vastgelegde app en de videofeeds van externe gebruikers niet tegelijkertijd zien, tenzij ze Picture-in-Picture gebruiken of aparte zij-aan-zij vensters voor het videoconferentietabblad en het gedeelde tabblad. Op een kleiner scherm kan dit lastig zijn.
- De gebruiker wordt belast door de noodzaak om tussen de videoconferentie-app en het vastgelegde oppervlak te springen.
- De gebruiker verliest de toegang tot de bedieningselementen die door de app voor videoconferenties worden weergegeven terwijl hij er niet is; bijvoorbeeld een ingebouwde 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 maar al te bekende scenario waarin externe gebruikers de presentator vragen om de dia te veranderen, een beetje op en neer te scrollen of het zoomniveau aan te passen.
De Captured Surface Control API lost deze problemen op.
Hoe gebruik ik Captured Surface Control?
Het succesvol gebruiken van Captured Surface Control vereist een paar stappen, zoals het expliciet vastleggen van een browsertabblad en het verkrijgen van toestemming van de gebruiker voordat hij kan scrollen en zoomen op het vastgelegde tabblad.
Leg een browsertabblad vast
Begin door de gebruiker te vragen een oppervlak te kiezen om te delen met behulp van getDisplayMedia() en koppel daarbij een CaptureController object aan de opnamesessie. We zullen dat object snel genoeg gebruiken om het veroverde oppervlak te controleren.
const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });
Maak vervolgens een lokaal voorbeeld van het vastgelegde oppervlak in de vorm van een <video> -element:
const previewTile = document.querySelector('video');
previewTile.srcObject = stream;
Als de gebruiker ervoor kiest een venster of scherm te delen, valt dat voorlopig buiten het bereik, maar als hij ervoor kiest een tabblad te delen, kunnen we doorgaan.
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 produceert een toestemmingsprompt. Als de gebruiker toestemming verleent, zijn verdere aanroepen van deze methoden toegestaan.
Een gebruikersgebaar is vereist om een toestemmingsprompt aan de gebruiker te tonen, dus de app mag de bovengenoemde methoden alleen aanroepen als deze al over de toestemming beschikt, of als reactie op een gebruikersgebaar, zoals een click op een relevante knop in de webapp.
Rol
Met behulp van forwardWheel() kan een vastleggende app wielgebeurtenissen doorsturen van een bronelement binnen de vastleggende app zelf naar de viewport van het vastgelegde tabblad. Deze gebeurtenissen zijn voor de vastgelegde app niet te onderscheiden van directe gebruikersinteractie.
Ervan uitgaande dat de opname-app een <video> -element gebruikt met de naam "previewTile" , laat de volgende code zien hoe stuurwielgebeurtenissen naar het vastgelegde tabblad kunnen worden doorgestuurd:
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() heeft één enkele invoer nodig, die een van de volgende kan zijn:
- Een HTML-element van waaruit wielgebeurtenissen worden doorgestuurd naar het vastgelegde tabblad.
-
null, wat aangeeft dat het doorsturen moet stoppen.
Een succesvolle aanroep van forwardWheel() overschrijft eerdere aanroepen.
De door forwardWheel() geretourneerde belofte kan in de volgende gevallen worden afgewezen:
- Als de opnamesessie nog niet is gestart of al is gestopt.
- Als de gebruiker de betreffende toestemming niet heeft verleend.
Zoom
Interactie met het zoomniveau van het vastgelegde tabblad vindt plaats via de volgende CaptureController API-oppervlakken:
getSupportedZoomLevels()
Deze methode retourneert een lijst met zoomniveaus die door de browser worden ondersteund voor het oppervlaktetype dat wordt vastgelegd. Waarden in deze lijst worden weergegeven als een percentage ten opzichte van het "standaardzoomniveau", dat is gedefinieerd als 100%. De lijst is monotoon stijgend en bevat de waarde 100.
Deze methode kan alleen worden aangeroepen voor ondersteunde typen weergaveoppervlakken, wat op dit moment alleen voor tabbladen betekent.
controller.getSupportedZoomLevels() kan worden aangeroepen als aan de volgende voorwaarden wordt voldaan:
-
controlleris geassocieerd met een actieve opname. - De opname is van een tabblad.
Anders wordt er een fout gegenereerd.
De toestemming "captured-surface-control" is niet vereist voor het aanroepen van deze methode.
zoomLevel
Dit alleen-lezen attribuut bevat het huidige zoomniveau van het vastgelegde tabblad. Het is een null-attribuut en blijft null als het vastgelegde oppervlaktetype geen betekenisvolle definitie van zoomniveau heeft. Op dit moment is het zoomniveau alleen gedefinieerd voor tabbladen, en niet voor vensters of schermen.
Nadat het vastleggen is beëindigd, behoudt het attribuut de laatste zoomniveauwaarde.
De machtiging "captured-surface-control" is niet vereist voor het lezen van dit kenmerk.
onzoomlevelchange
Deze gebeurtenishandler vergemakkelijkt het luisteren naar wijzigingen in het zoomniveau van het vastgelegde tabblad. Deze gebeuren ofwel:
- Wanneer de gebruiker interactie heeft met de browser om het zoomniveau van het vastgelegde tabblad handmatig te wijzigen.
- Als reactie op de aanroepen van de vastleggende app naar de zoominstellingsmethoden (hieronder beschreven).
De machtiging "captured-surface-control" is niet vereist voor het lezen van dit kenmerk.
increaseZoomLevel() , decreaseZoomLevel() en resetZoomLevel()
Deze methoden maken manipulatie van het zoomniveau van het vastgelegde tabblad mogelijk.
increaseZoomLevel() en decreaseZoomLevel() wijzigen het zoomniveau naar respectievelijk het volgende of vorige zoomniveau, volgens de volgorde die wordt geretourneerd door getSupportedZoomLevels() . resetZoomLevel() stelt de waarde in op 100.
Voor het aanroepen van deze methoden is de toestemming "captured-surface-control" vereist. Als de opname-app deze toestemming niet heeft, wordt de gebruiker gevraagd deze toestemming te verlenen of te weigeren.
Deze methoden retourneren allemaal een belofte die wordt opgelost als de oproep succesvol is en anders wordt afgewezen. Mogelijke oorzaken voor afwijzing zijn onder meer:
- Ontbrekende toestemming.
- Gebeld voordat de vangst begon.
- Gebeld nadat de gevangenneming was geëindigd.
- Er is een
controlleropgeroepen die is gekoppeld aan een opname van een niet-ondersteund type weergaveoppervlak. (Dat wil zeggen, alles behalve het vastleggen van tabbladen.) - Pogingen om respectievelijk de maximale of minimale waarde te verhogen of te verlagen.
Het wordt met name aanbevolen om te voorkomen dat u decreaseZoomLevel() aanroept als controller.zoomLevel == controller.getSupportedZoomLevels().at(0) , en om oproepen naar increaseZoomLevel() op vergelijkbare wijze te bewaken met .at(-1) .
In het volgende voorbeeld ziet u hoe u de gebruiker het zoomniveau van een vastgelegd tabblad rechtstreeks vanuit de vastgelegde app kunt laten 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 kunt reageren 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 ook mogelijk om een van de andere Captured Surface Control API-oppervlakken te gebruiken, zoals increaseZoomLevel of decreaseZoomLevel , of zelfs om ze allemaal te controleren.
Browser-ondersteuning
Captured Surface Control is alleen beschikbaar vanaf Chrome 136 op desktop.
Beveiliging en privacy
Met het toestemmingsbeleid "captured-surface-control" kunt u beheren hoe uw capture-app en ingebedde iframes van derden toegang hebben tot Captured Surface Control. Om de afwegingen op het gebied van beveiliging te begrijpen, bekijk je het gedeelte Privacy- en beveiligingsoverwegingen van de uitleg over Captured Surface Control.
Demo
Je kunt met Captured Surface Control spelen door de demo op Glitch uit te voeren. Zorg ervoor dat u de broncode bekijkt .
Feedback
Het Chrome-team en de webstandaardgemeenschap willen graag horen over uw ervaringen met Captured Surface Control.
Vertel ons over het ontwerp
Is er iets aan Captured Surface Capture dat niet werkt zoals je had verwacht? Of ontbreken er methoden of eigenschappen die je nodig hebt om je idee te implementeren? Heeft u een vraag of opmerking over het beveiligingsmodel? Dien een spec-probleem in op de GitHub-repository of voeg uw mening toe aan een bestaand probleem.
Probleem met de implementatie?
Heeft u een bug gevonden in de implementatie van Chrome? Of wijkt de uitvoering af van de specificaties? Dien een bug in op https://new.crbug.com . Zorg ervoor dat u zoveel mogelijk details vermeldt, evenals instructies voor reproductie. Glitch werkt prima voor het delen van reproduceerbare bugs.