Udostępnianie kart, okien i ekranów jest już możliwe na platformie internetowej dzięki interfejsowi Screen Capture API. Gdy aplikacja internetowa wywoła getDisplayMedia(), Chrome wyświetli prośbę o udostępnienie aplikacji internetowej karty, okna lub ekranu jako MediaStreamTrack wideo.
Wiele aplikacji internetowych korzystających z getDisplayMedia() wyświetla użytkownikowi podgląd wideo zarejestrowanej powierzchni. Na przykład aplikacje do wideokonferencji często przesyłają ten film do użytkowników zdalnych, a także renderują go na lokalnym HTMLVideoElement, dzięki czemu lokalny użytkownik może stale widzieć podgląd tego, co udostępnia.
W tym dokumencie przedstawiamy nowy interfejs Captured Surface Control API w Chrome, który umożliwia przewijanie przechwyconej karty w aplikacji internetowej, a także odczytywanie i zapisywanie poziomu powiększenia przechwyconej karty.
Dlaczego warto korzystać z funkcji Captured Surface Control?
Wszystkie aplikacje do wideokonferencji mają tę samą wadę. Jeśli użytkownik chce wejść w interakcję z przechwyconą kartą lub oknem, musi przełączyć się na tę powierzchnię, co spowoduje opuszczenie aplikacji do wideokonferencji. Wiąże się to z pewnymi problemami:
- Użytkownik nie może jednocześnie widzieć przechwyconej aplikacji i strumieni wideo zdalnych użytkowników, chyba że korzysta z funkcji Obraz w obrazie lub osobnych okien obok siebie na karcie konferencji wideo i udostępnionej karcie. Na mniejszym ekranie może to być trudne.
- Użytkownik musi przełączać się między aplikacją do obsługi rozmów wideo a nagrywaną powierzchnią.
- Użytkownik traci dostęp do elementów sterujących udostępnianych przez aplikację do wideokonferencji, gdy nie korzysta z niej. Dotyczy to na przykład wbudowanej aplikacji do czatu, reakcji emoji, powiadomień o prośbach użytkowników o dołączenie do połączenia, elementów sterujących multimediami i układem oraz innych przydatnych funkcji wideokonferencji.
- Prezentujący nie może przekazać kontroli uczestnikom zdalnym. Prowadzi to do dobrze znanego scenariusza, w którym użytkownicy zdalni proszą prezentera o zmianę slajdu, przewinięcie w górę i w dół lub dostosowanie poziomu powiększenia.
Interfejs Captured Surface Control API rozwiązuje te problemy.
Jak korzystać z funkcji Captured Surface Control?
Aby skutecznie korzystać z funkcji sterowania przechwyconą powierzchnią, musisz wykonać kilka czynności, np. wyraźnie przechwycić kartę przeglądarki i uzyskać zgodę użytkownika, zanim będzie można przewijać i powiększać przechwyconą kartę.
Rejestrowanie karty przeglądarki
Zacznij od poproszenia użytkownika o wybranie platformy do udostępniania za pomocą getDisplayMedia(), a następnie powiąż obiekt CaptureController z sesją przechwytywania. Wkrótce będziemy 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 zarejestrowanej 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 zrobić. Jeśli jednak zdecyduje się udostępnić kartę, możemy kontynuować.
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() na danym obiekcie CaptureController powoduje wyświetlenie prośby o uprawnienia. Jeśli użytkownik przyzna uprawnienia, dalsze wywołania tych metod będą dozwolone.
Aby wyświetlić użytkownikowi prośbę o uprawnienia, wymagany jest gest użytkownika, więc aplikacja powinna wywoływać wspomniane metody tylko wtedy, gdy ma już uprawnienia lub w odpowiedzi na gest użytkownika, np. click na odpowiednim przycisku w aplikacji internetowej.
Przewiń
Za pomocą interfejsu forwardWheel() aplikacja przechwytująca może przekazywać zdarzenia kółka z elementu źródłowego w samej aplikacji przechwytującej do obszaru widoku przechwyconej karty. Dla zarejestrowanej aplikacji te zdarzenia są nieodróżnialne od bezpośredniej interakcji użytkownika.
Załóżmy, że aplikacja przechwytująca używa elementu <video> o nazwie "previewTile". Poniższy kod pokazuje, jak przekazywać zdarzenia przewijania do przechwyconej karty:
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 1 dane wejściowe, które mogą być jednym z tych typów:
- Element HTML, z którego zdarzenia związane z kółkiem myszy będą przekazywane do przechwyconej karty.
null, co oznacza, że przekazywanie powinno się zakończyć.
Pomyślne wywołanie funkcji forwardWheel() zastępuje poprzednie wywołania.
Obietnica zwrócona przez funkcję forwardWheel() może zostać odrzucona w tych przypadkach:
- Jeśli sesja przechwytywania jeszcze się nie rozpoczęła lub już się zakończyła.
- Jeśli użytkownik nie przyznał odpowiednich uprawnień.
Zoom
Interakcja z poziomem powiększenia przechwyconej karty odbywa się za pomocą tych CaptureController interfejsów API:
getSupportedZoomLevels()
Ta metoda zwraca listę poziomów powiększenia obsługiwanych przez przeglądarkę w przypadku typu powierzchni, która jest rejestrowana. Wartości na tej liście są podawane w procentach w stosunku do „domyślnego poziomu powiększenia”, który jest zdefiniowany jako 100%. Lista jest monotonicznie rosnąca i zawiera wartość 100.
Tej metody można używać 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 nagraniem.- Zapis dotyczy karty.
W przeciwnym razie pojawi się błąd.
Do wywołania tej metody nie jest wymagane uprawnienie "captured-surface-control".
zoomLevel
Ten atrybut tylko do odczytu zawiera bieżący poziom powiększenia zarejestrowanej karty. Jest to atrybut dopuszczający wartość null. Jeśli typ zarejestrowanej powierzchni nie ma znaczącej definicji poziomu powiększenia, przyjmuje wartość null. Obecnie poziom powiększenia jest określany tylko w przypadku kart, a nie okien ani ekranów.
Po zakończeniu przechwytywania atrybut będzie zawierać wartość ostatniego poziomu powiększenia.
Uprawnienie "captured-surface-control" nie jest wymagane do odczytania tego atrybutu.
onzoomlevelchange
Ten moduł obsługi zdarzeń ułatwia nasłuchiwanie zmian poziomu powiększenia przechwyconej karty. Dzieje się to w jeden z tych sposobów:
- Gdy użytkownik wejdzie w interakcję z przeglądarką, aby ręcznie zmienić poziom powiększenia przechwyconej karty.
- W odpowiedzi na wywołania metod ustawiania powiększenia przez aplikację rejestrującą (opisane poniżej).
Uprawnienie "captured-surface-control" nie jest wymagane do odczytania tego atrybutu.
increaseZoomLevel(), decreaseZoomLevel() i resetZoomLevel()
Te metody umożliwiają zmianę poziomu powiększenia przechwyconej karty.
increaseZoomLevel() i decreaseZoomLevel() zmieniają poziom powiększenia na następny lub poprzedni poziom powiększenia zgodnie z kolejnością zwracaną przez getSupportedZoomLevels(). resetZoomLevel() ustawia wartość na 100.
Do wywoływania tych metod wymagane jest uprawnienie "captured-surface-control". Jeśli aplikacja przechwytująca nie ma tego uprawnienia, użytkownik zobaczy prośbę o jego przyznanie lub odrzucenie.
Wszystkie te metody zwracają obietnicę, która jest spełniana, jeśli wywołanie się powiedzie, a w przeciwnym razie jest odrzucana. Możliwe przyczyny odrzucenia:
- Brak uprawnień.
- Połączenie zostało wykonane przed rozpoczęciem nagrywania.
- Wywołanie po zakończeniu przechwytywania.
- Wywołano w
controllerpowiązanym z przechwytywaniem nieobsługiwanego typu powierzchni wyświetlania. (czyli wszystko oprócz przechwytywania karty). - Próby zwiększenia lub zmniejszenia wartości poza odpowiednio maksymalną lub minimalną wartość.
W szczególności zaleca się unikanie dzwonienia pod numer decreaseZoomLevel(), jeśli controller.zoomLevel == controller.getSupportedZoomLevels().at(0), oraz podobne zabezpieczanie połączeń z numerem increaseZoomLevel() za pomocą .at(-1).
Poniższy przykład pokazuje, jak umożliwić użytkownikowi zwiększenie poziomu powiększenia przechwyconej karty bezpośrednio z aplikacji przechwytującej:
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 przechwyconej karty:
controller.addEventListener('zoomlevelchange', (event) => {
const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});
Wykrywanie cech
Aby sprawdzić, czy interfejsy Captured Surface Control API są obsługiwane, użyj tego polecenia:
if (!!window.CaptureController?.prototype.forwardWheel) {
// CaptureController forwardWheel() is supported.
}
Możesz też użyć dowolnej innej powierzchni interfejsu Captured Surface Control API, np. increaseZoomLevel lub decreaseZoomLevel, albo sprawdzić wszystkie te powierzchnie.
Obsługa przeglądarek
Funkcja przechwytywania kontroli nad powierzchnią jest dostępna tylko na komputerach w Chrome w wersji 136 lub nowszej.
Bezpieczeństwo i prywatność
"captured-surface-control" Zasady dotyczące uprawnień umożliwiają zarządzanie dostępem aplikacji do przechwytywania i osadzonych ramek iframe innych firm do funkcji Captured Surface Control. Aby dowiedzieć się więcej o kompromisach w zakresie bezpieczeństwa, zapoznaj się z sekcją Kwestie związane z prywatnością i bezpieczeństwem w wyjaśnieniu dotyczącym funkcji sterowania przechwyconą powierzchnią.
Prezentacja
Możesz wypróbować funkcję Captured Surface Control, uruchamiając wersję demonstracyjną.
Prześlij opinię
Zespół Chrome i społeczność zajmująca się standardami internetowymi chcą poznać Twoje wrażenia związane z funkcją Captured Surface Control.
Opisz projekt
Czy coś w funkcji przechwytywania powierzchni nie działa zgodnie z oczekiwaniami? Czy brakuje metod lub właściwości, które są potrzebne do realizacji Twojego pomysłu? Masz pytania lub uwagi dotyczące modelu zabezpieczeń? Zgłoś problem ze specyfikacją w repozytorium GitHub lub dodaj swoje uwagi do istniejącego problemu.
Masz problem z implementacją?
Czy w implementacji Chrome występuje błąd? 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 i instrukcje odtwarzania problemu.