Udostępnianie kart, okien i ekranów jest już możliwe na platformie internetowej dzięki interfejsowi Screen Capture API. Gdy aplikacja internetowa wywołuje getDisplayMedia(), Chrome prosi użytkownika o udostępnienie jej karty, okna lub ekranu w postaci MediaStreamTrack filmu.
Wiele aplikacji internetowych, które korzystają z getDisplayMedia(), wyświetla użytkownikowi podgląd wideo z przechwyczonej powierzchni. Na przykład aplikacje do wideokonferencji często przesyłają strumień wideo do użytkowników zdalnych, a zarazem renderują go lokalnie HTMLVideoElement, aby użytkownik lokalny stale widział podgląd tego, co udostępnia.
Ta dokumentacja przedstawia nowy interfejs Captured Surface Control API w Chrome, który umożliwia aplikacji internetowej przewijanie przechwyczonej karty oraz odczyt i zapisywanie poziomu powiększenia tej karty.
Dlaczego warto korzystać z Captured Surface Control?
Wszystkie aplikacje do rozmów wideo mają ten sam problem. Jeśli użytkownik chce wejść w interakcję z przechwyconą kartą lub oknem, musi przełączyć się na tę powierzchnię, opuszczając aplikację do wideokonferencji. Stwarza to pewne problemy:
- Użytkownik nie może jednocześnie widzieć przechwyczonej aplikacji i obrazu wideo z mówcami, chyba że korzysta z obrazu w obrazie lub oddzielnych okien obok siebie na kartę konferencji wideo i kartę udostępnioną. Na mniejszym ekranie może to być trudne.
- Użytkownik musi przełączać się między aplikacją do rozmów wideo a uchwytem.
- Użytkownik traci dostęp do elementów sterujących udostępnianych przez aplikację do konferencji wideo, gdy nie korzysta z tej aplikacji. Na przykład nie może korzystać z wbudowanej aplikacji do czatu, reakcji emotikonami, powiadomień o użytkownikach proszących o dołączenie do rozmowy, elementów sterujących multimediami i układem oraz innych przydatnych funkcji konferencji wideo.
- Prezenter nie może przekazać kontroli uczestnikom zdalnym. W efekcie użytkownicy zdalni proszą prowadzącego o zmianę slajdu, przewinięcie w górę lub w dół albo dostosowanie poziomu powiększenia.
Interfejs Captured Surface Control API rozwiązuje te problemy.
Jak korzystać z Captured Surface Control?
Aby można było korzystać z zarządzania przechwyconym interfejsem, należy wykonać kilka czynności, takich jak wyraźne przechwycenie karty przeglądarki i uzyskanie zgody użytkownika, zanim będzie można przewijać i powiększać przechwyconą kartę.
Rejestrowanie karty przeglądarki
Najpierw poproś użytkownika o wybranie powierzchni do udostępnienia za pomocą getDisplayMedia(), a potem powiązaj obiekt CaptureController z sesją rejestrowania. Wkrótce zaczniemy używać tego obiektu do kontrolowania przechwyconej powierzchni.
const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });
Następnie wygeneruj lokalny podgląd sfilmowanej powierzchni w postaci elementu <video>:
const previewTile = document.querySelector('video');
previewTile.srcObject = stream;
Jeśli użytkownik zdecyduje się udostępnić okno lub ekran, nie będziemy mogli tego obsłużyć. Jeśli jednak zdecyduje się udostępnić kartę, możemy to zrobić.
const [track] = stream.getVideoTracks();
if (track.getSettings().displaySurface !== 'browser') {
// Bail out early if the user didn't pick a tab.
return;
}
Prośba o uprawnienia
Pierwsze wywołanie funkcji forwardWheel(), increaseZoomLevel(), decreaseZoomLevel() lub resetZoomLevel() w danym obiekcie CaptureController powoduje wyświetlenie prośby o uprawnienia. Jeśli użytkownik udzieli zgody, dalsze wywołania tych metod będą dozwolone.
Aby wyświetlić użytkownikowi prośbę o uprawnienia, aplikacja musi wykryć jego działanie. Dlatego powinna wywoływać wspomniane wyżej metody tylko wtedy, gdy ma już uprawnienia lub gdy użytkownik wykona odpowiednie działanie, np. kliknie click na odpowiednim przycisku w aplikacji internetowej.
Przewiń
Za pomocą forwardWheel() aplikacja do przechwytywania może przekazywać zdarzenia koła z elementu źródłowego w aplikacji do przechwytywania do widoku przechwyczonej karty. Te zdarzenia są dla aplikacji uchwyconej w zbieranie danych nie do odróżnienia od bezpośredniej interakcji użytkownika.
Zakładając, że aplikacja do przechwytywania używa elementu <video> o nazwie "previewTile", poniższy kod pokazuje, jak przekazywać zdarzenia kółka do wysyłania do karty przechwytywania:
const previewTile = document.querySelector('video');
try {
// Relay the user's action to the captured tab.
await controller.forwardWheel(previewTile);
} catch (error) {
// Inspect the error.
// ...
}
Metoda forwardWheel() przyjmuje jeden argument, który może być:
- Element HTML, z którego zdarzenia koła będą przekazywane do karty przechwytywania.
null, co oznacza, że przekierowanie powinno zostać zatrzymane.
Pomyślne wywołanie funkcji forwardWheel() zastąpi poprzednie wywołania.
Obietnica z poziomu forwardWheel() może zostać odrzucona w tych przypadkach:
- Jeśli sesja przechwytywania nie została jeszcze uruchomiona lub została już zatrzymana.
- Jeśli użytkownik nie udzielił odpowiedniego uprawnienia.
Zoom
Interakcje z poziomem powiększenia przechwyconego elementu są realizowane za pomocą tych interfejsów API:CaptureController
getSupportedZoomLevels()
Ta metoda zwraca listę poziomów powiększenia obsługiwanych przez przeglądarkę dla rejestrowanego typu powierzchni. Wartości na tej liście są podawane w procentach w odniesieniu do „domyślnego poziomu powiększenia”, który jest zdefiniowany jako 100%. Lista jest monotonicznie rosnąca i zawiera wartość 100.
Ta metoda może być wywoływana tylko w przypadku obsługiwanych typów powierzchni wyświetlania, co obecnie oznacza tylko karty.
Funkcja controller.getSupportedZoomLevels() może zostać wywołana, jeśli spełnione są te warunki:
controllerjest powiązany z aktywnym przechwyceniem.- Zrzut ekranu karty.
W przeciwnym razie zostanie wyświetlony komunikat o błędzie.
Uprawnienie "captured-surface-control" nie jest wymagane do wywołania tej metody.
zoomLevel
Ten atrybut tylko do odczytu zawiera bieżący poziom powiększenia uchwyconej karty. Jest to atrybut, który może być pusty. Zawiera wartość null, jeśli typ uchwyczonej powierzchni nie ma sensownej definicji poziomu powiększenia. Obecnie poziom powiększenia jest zdefiniowany tylko dla kart, a nie okien ani ekranów.
Po zakończeniu rejestrowania atrybutu zostanie zachowana ostatnia wartość poziomu powiększenia.
Uprawnienia "captured-surface-control" nie są wymagane do odczytania tego atrybutu.
onzoomlevelchange
Ten przetwarzacz zdarzeń ułatwia nasłuchiwanie zmian poziomu powiększenia na zarejestrowanej karcie. Mogą one wystąpić w jednym z tych przypadków:
- Gdy użytkownik wejdzie w interakcję z przeglądarką, aby ręcznie zmienić poziom powiększenia przechwyconego elementu.
- W odpowiedzi na wywołania metod ustawień powiększenia (opisane poniżej) przez aplikację do rejestrowania.
Uprawnienia "captured-surface-control" nie są wymagane do odczytania tego atrybutu.
increaseZoomLevel(), decreaseZoomLevel() i resetZoomLevel()
Te metody umożliwiają manipulowanie poziomem powiększenia uchwyconej karty.
Parametry increaseZoomLevel() i decreaseZoomLevel() zmieniają poziom powiększenia odpowiednio na następny lub poprzedni zgodnie z kolejnością zwracaną przez funkcję getSupportedZoomLevels(). resetZoomLevel() ustawia wartość na 100.
Do wywoływania tych metod wymagane jest uprawnienie "captured-surface-control". Jeśli aplikacja do rejestrowania nie ma tego uprawnienia, użytkownik zobaczy prośbę o jego przyznanie lub odrzucenie.
Wszystkie te metody zwracają obietnicę, która jest spełniona, jeśli wywołanie się powiedzie, a w przeciwnym razie zostaje odrzucona. Możliwe przyczyny odrzucenia:
- Brak uprawnień.
- Połączenie zostało wykonane przed rozpoczęciem przechwytywania.
- Wywołany po zakończeniu przechwytywania.
- Wywoływany w przypadku
controllerpowiązanego z przechwyceniem nieobsługiwanego typu powierzchni wyświetlacza. (czyli wszystko oprócz przechwytywania karty). - Próbuje zwiększyć lub zmniejszyć wartość poza maksymalną lub minimalną wartość.
Zalecamy unikanie dzwonienia na numer decreaseZoomLevel(), jeśli controller.zoomLevel == controller.getSupportedZoomLevels().at(0), oraz blokowanie połączeń na numer increaseZoomLevel() w podobny sposób za pomocą funkcji .at(-1).
Ten przykład pokazuje, jak umożliwić użytkownikowi zwiększenie poziomu powiększenia przechwyconej karty bezpośrednio z aplikacji do przechwytywania:
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.
// ...
}
});
Z poniższego przykładu dowiesz się, jak reagować na zmiany poziomu powiększenia uchwyczonej karty:
controller.addEventListener('zoomlevelchange', (event) => {
const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});
Wykrywanie funkcji
Aby sprawdzić, czy interfejsy Captured Surface Control API są obsługiwane, użyj:
if (!!window.CaptureController?.prototype.forwardWheel) {
// CaptureController forwardWheel() is supported.
}
Możesz też użyć dowolnej innej interfejsu interfejsu API Captured Surface Control, np. increaseZoomLevel lub decreaseZoomLevel, a nawet sprawdzić wszystkie.
Obsługa przeglądarek
Funkcja Captured Surface Control jest dostępna w Chrome 136 tylko na komputerach.
Bezpieczeństwo i prywatność
Zasady uprawnień "captured-surface-control" umożliwiają zarządzanie dostępem aplikacji do rejestrowania i osadzonych ramek iframe innych firm do funkcji sterowania powierzchnią rejestrowania. Aby poznać kompromisy związane z bezpieczeństwem, przeczytaj sekcję Prywatność i bezpieczeństwo w artykule na temat kontrolowania urządzeń rejestrujących.
Prezentacja
Możesz korzystać z Captured Surface Control, uruchamiając demo w Glitch. Pamiętaj, aby sprawdzić kod źródłowy.
Prześlij opinię
Zespół Chrome i społeczność zajmująca się standardami internetowymi chce poznać Twoje wrażenia związane z użyciem funkcji Captured Surface Control.
Opowiedz nam o projektowaniu
Czy coś w Captured Surface Capture nie działa zgodnie z oczekiwaniami? A może brakuje metod lub właściwości, których potrzebujesz do wdrożenia swojego pomysłu? Masz pytania lub uwagi dotyczące modelu zabezpieczeń? Zgłoś problem ze specyfikacją w repozytorium GitHub lub podziel się opinią na temat istniejącego problemu.
Problem z implementacją?
Czy znalazłeś/znalazłaś błąd w implementacji Chrome? A może implementacja różni się od specyfikacji? Zgłoś błąd na stronie https://new.crbug.com. Podaj jak najwięcej szczegółów, a także instrukcje odtwarzania błędu. Glitch świetnie sprawdza się do udostępniania błędów, które można odtworzyć.