Прокрутка и масштабирование захваченной вкладки

Франсуа Бофор
François Beaufort
GitHub
Элад Алон

Совместное использование вкладок, окон и экранов уже возможно на веб-платформе с помощью API захвата экрана . Когда веб-приложение вызывает getDisplayMedia() , Chrome предлагает пользователю поделиться вкладкой, окном или экраном с веб-приложением в виде видео MediaStreamTrack .

Многие веб-приложения, использующие getDisplayMedia() , показывают пользователю видеопревью захваченной поверхности. Например, приложения для видеоконференций часто транслируют это видео удалённым пользователям, одновременно отображая его в локальном HTMLVideoElement , чтобы локальный пользователь постоянно видел превью того, чем он делится.

В этой документации представлен новый API управления захваченной поверхностью в Chrome, который позволяет вашему веб-приложению прокручивать захваченную вкладку, а также считывать и записывать уровень масштабирования захваченной вкладки.

Пользователь прокручивает и масштабирует захваченную вкладку ( демонстрация ).

Зачем использовать Captured Surface Control?

Все приложения для видеоконференций страдают от одного и того же недостатка. Если пользователь хочет взаимодействовать с захваченной вкладкой или окном, ему приходится переключаться на эту поверхность, отвлекаясь от приложения для видеоконференций. Это создаёт некоторые трудности:

  • Пользователь не сможет одновременно видеть захваченное приложение и видеопотоки удалённых пользователей, если не использует функцию «Картинка в картинке» или не использует отдельные окна рядом для вкладки видеоконференции и общей вкладки. На небольшом экране это может быть затруднительно.
  • Пользователю приходится постоянно переключаться между приложением для видеоконференций и поверхностью, на которую ведется видеосъёмка.
  • Пользователь теряет доступ к элементам управления, предоставляемым приложением для видеоконференций, когда он находится вне его пределов; например, к встроенному приложению чата, реакциям в виде эмодзи, уведомлениям о пользователях, желающих присоединиться к вызову, элементам управления мультимедиа и макетом, а также другим полезным функциям видеоконференций.
  • Докладчик не может делегировать управление удалённым участникам. Это приводит к слишком знакомой ситуации, когда удалённые пользователи просят докладчика сменить слайд, немного прокрутить презентацию вверх или вниз или изменить масштаб.

API Captured Surface Control решает эти проблемы.

Как использовать Captured Surface Control?

Для успешного использования Captured Surface Control требуется выполнить несколько шагов, таких как явный захват вкладки браузера и получение разрешения от пользователя, прежде чем можно будет прокручивать и масштабировать захваченную вкладку.

Захват вкладки браузера

Сначала предложите пользователю выбрать поверхность для совместного использования с помощью getDisplayMedia() , а затем свяжите объект CaptureController с сеансом захвата. Вскоре мы будем использовать этот объект для управления захваченной поверхностью.

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

Далее создадим локальный предварительный просмотр захваченной поверхности в виде элемента <video> :

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

Если пользователь выбирает совместное использование окна или экрана, то это пока выходит за рамки наших возможностей, но если он выбирает совместное использование вкладки, мы можем продолжить.

const [track] = stream.getVideoTracks();

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

Запрос на разрешение

Первый вызов метода forwardWheel() , increaseZoomLevel() , decreaseZoomLevel() или resetZoomLevel() для заданного объекта CaptureController приводит к запросу разрешения. Если пользователь даёт разрешение, дальнейшие вызовы этих методов разрешены.

Для отображения запроса на разрешение пользователю необходим жест пользователя, поэтому приложение должно вызывать вышеупомянутые методы только в том случае, если у него уже есть разрешение, или в ответ на жест пользователя, например click соответствующей кнопки в веб-приложении.

Прокрутить

Используя forwardWheel() , приложение, осуществляющее захват, может пересылать события колеса прокрутки из исходного элемента внутри самого приложения, в область просмотра захваченной вкладки. Эти события неотличимы для захваченного приложения от прямого взаимодействия с пользователем.

Предполагая, что приложение захвата использует элемент <video> с названием "previewTile" , следующий код показывает, как передать события отправки колеса на захваченную вкладку:

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

Метод forwardWheel() принимает один входной параметр, который может быть одним из следующих:

  • HTML-элемент, из которого события колеса будут пересылаться на захваченную вкладку.
  • null , что указывает на то, что пересылку следует прекратить.

Успешный вызов forwardWheel() переопределяет предыдущие вызовы.

Обещание, возвращаемое forwardWheel() может быть отклонено в следующих случаях:

  • Если сеанс захвата еще не начался или уже остановлен.
  • Если пользователь не предоставил соответствующее разрешение.

Увеличить

Взаимодействие с уровнем масштабирования захваченной вкладки осуществляется через следующие поверхности API CaptureController :

getSupportedZoomLevels()

Этот метод возвращает список уровней масштабирования, поддерживаемых браузером для типа снимаемой поверхности. Значения в этом списке представлены в процентах относительно «уровня масштабирования по умолчанию», который определяется как 100%. Список монотонно увеличивается и содержит значение 100.

Этот метод может быть вызван только для поддерживаемых типов поверхностей отображения, что на данный момент означает только для вкладок.

controller.getSupportedZoomLevels() может быть вызван, если выполняются следующие условия:

  • controller связан с активным захватом.
  • На снимке изображена вкладка.

В противном случае возникнет ошибка.

Для вызова этого метода разрешение "captured-surface-control" не требуется.

zoomLevel

Этот атрибут, доступный только для чтения, содержит текущий уровень масштабирования захваченной вкладки. Он может иметь значение NULL и принимает значение null , если тип захваченной поверхности не имеет осмысленного определения уровня масштабирования. В настоящее время уровень масштабирования определен только для вкладок, но не для окон или экранов.

После завершения захвата атрибут будет содержать последнее значение уровня масштабирования.

Для чтения этого атрибута разрешение "captured-surface-control" не требуется.

onzoomlevelchange

Этот обработчик событий позволяет отслеживать изменения уровня масштабирования захваченной вкладки. Они происходят в следующих случаях:

  • Когда пользователь взаимодействует с браузером, чтобы вручную изменить уровень масштабирования захваченной вкладки.
  • В ответ на вызовы приложением захвата методов настройки масштаба (описанных ниже).

Для чтения этого атрибута разрешение "captured-surface-control" не требуется.

increaseZoomLevel() , decreaseZoomLevel() и resetZoomLevel()

Эти методы позволяют манипулировать уровнем масштабирования захваченной вкладки.

increaseZoomLevel() и decreaseZoomLevel() изменяют уровень масштабирования на следующий или предыдущий уровень масштабирования соответственно в соответствии с порядком, возвращаемым getSupportedZoomLevels() . resetZoomLevel() устанавливает значение 100.

Для вызова этих методов требуется разрешение "captured-surface-control" . Если у приложения, выполняющего захват, этого разрешения нет, пользователю будет предложено предоставить или отклонить его.

Все эти методы возвращают обещание, которое разрешается в случае успешного вызова и отклоняется в противном случае. Возможные причины отклонения:

  • Отсутствует разрешение.
  • Позвонили перед началом захвата.
  • Вызвали после окончания захвата.
  • Вызывается на controller , связанном с захватом неподдерживаемого типа поверхности отображения. (То есть, любого, кроме захвата вкладки.)
  • Попытки увеличить или уменьшить значение, превышающее максимальное или минимальное соответственно.

В частности, рекомендуется избегать вызова decreaseZoomLevel() если controller.zoomLevel == controller.getSupportedZoomLevels().at(0) , и защищать вызовы increaseZoomLevel() аналогичным образом с помощью .at(-1) .

В следующем примере показано, как разрешить пользователю увеличивать уровень масштабирования захваченной вкладки непосредственно из приложения, с которого был сделан захват:

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

В следующем примере показано, как реагировать на изменение уровня масштабирования захваченной вкладки:

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

Обнаружение особенностей

Чтобы проверить, поддерживаются ли API Captured Surface Control, используйте:

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

В равной степени возможно использовать любую из других поверхностей API Captured Surface Control, например increaseZoomLevel или decreaseZoomLevel , или даже проверять их все.

Поддержка браузеров

Captured Surface Control доступен только на настольных компьютерах, начиная с Chrome 136.

Безопасность и конфиденциальность

Политика разрешений "captured-surface-control" позволяет вам управлять доступом вашего приложения для захвата и встроенных сторонних iframe к Captured Surface Control. Чтобы понять компромиссы в плане безопасности, ознакомьтесь с разделом « Вопросы конфиденциальности и безопасности» в руководстве по Captured Surface Control.

Демо

Вы можете поэкспериментировать с Captured Surface Control, запустив демо-версию .

Обратная связь

Команда Chrome и сообщество веб-стандартов хотят узнать о вашем опыте использования Captured Surface Control.

Расскажите нам о дизайне

Есть ли что-то в Captured Surface Capture, что работает не так, как вы ожидали? Или отсутствуют методы или свойства, необходимые для реализации вашей идеи? Есть вопрос или комментарий по модели безопасности? Отправьте запрос на спецификацию в репозиторий GitHub или добавьте свои замечания к существующему запросу.

Проблема с реализацией?

Вы обнаружили ошибку в реализации Chrome? Или реализация отличается от спецификации? Сообщите об ошибке на сайте https://new.crbug.com . Опишите проблему как можно подробнее, а также приложите инструкции по её воспроизведению.