Przewijanie i powiększanie przechwyconej karty

François Beaufort
François Beaufort
GitHub
Elad Alon

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 także 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.

Użytkownik przewija i powiększa przechwyconą kartę (demo).

Dlaczego warto korzystać z Captured Surface Control?

Wszystkie aplikacje do rozmów wideo mają ten sam minus. 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 niej. Na przykład dostępnych jest mniej funkcji, takich jak wbudowana aplikacja do czatu, reakcje emotikonami, powiadomienia o żądaniu dołączenia do rozmowy, elementy sterujące multimediami i układem oraz inne przydatne funkcje 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(). W tym celu 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 koła do przechwyczonej 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 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 CaptureControllerAPI:

getSupportedZoomLevels()

Ta metoda zwraca listę poziomów powiększenia obsługiwanych przez przeglądarkę dla danego typu powierzchni. 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.

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:

  • controller jest 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 atrybuty będą zawierać ostatnią 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ą wystąpić następujące sytuacje:

  • 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 (opisanych 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.

increaseZoomLevel() i decreaseZoomLevel() zmieniają poziom powiększenia odpowiednio na następny lub poprzedni 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 do rejestrowania nie ma tego uprawnienia, użytkownik zobaczy prośbę o jego przyznanie lub odrzucenie.

Wszystkie te metody zwracają obietnicę, która jest realizowana, 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 przechwytywania.
  • Wywołany po zakończeniu przechwytywania.
  • Funkcja jest wywoływana na controller powiązanym 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, aby unikać dzwonienia na numer decreaseZoomLevel(), jeśli controller.zoomLevel == controller.getSupportedZoomLevels().at(0), oraz blokować połączenia 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 uchwyconej 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 powierzchni interfejsu API Captured Surface Control, np. increaseZoomLevel lub decreaseZoomLevel, a nawet sprawdzić je 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 projektie

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.