API визуального области просмотра

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

В мобильной веб-среде есть два вида области просмотра: область просмотра макета и визуальная область просмотра. Область просмотра макета охватывает все элементы на странице, а визуальная область просмотра — это то, что фактически отображается на экране. При масштабировании страницы пользователем с помощью пинцета визуальная область просмотра уменьшается, но область просмотра макета остается неизменной. Элементы пользовательского интерфейса, такие как наложенная клавиатура (OSK), могут уменьшать визуальную область просмотра, не затрагивая область просмотра макета.

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

Для доступа к визуальной области просмотра окна вы можете получить объект VisualViewport из свойства window.visualViewport. Объект включает набор свойств, описывающих область просмотра. Он также добавляет три события: resize, scroll и scrollend, которые срабатывают соответственно при изменении размера визуальной области просмотра, прокрутке и завершении действия прокрутки.

Первые два события позволяют позиционировать элементы относительно визуальной области просмотра при прокрутке или масштабировании, которые обычно привязаны к области просмотра макета. Событие scrollend позволяет обновлять элемент при завершении действия прокрутки. Например, вы можете использовать эти события для сохранения элемента, закрепленного за визуальной областью просмотра при масштабировании и прокрутке, и обновления его при завершении прокрутки.

VisualViewport

Представляет визуальную область просмотра для данного окна. Объект VisualViewport окна предоставляет информацию о положении и размере области просмотра и получает события resize, scroll и scrollend.

Window.visualViewport Только для чтения

Только для чтения ссылка на объект визуальной области просмотра окна VisualViewport. Если этого свойства нет, API не поддерживается.

Наш пример API визуального области просмотра предоставляет базовую демонстрацию работы различных функций визуальной области просмотра, включая три типа событий. Загрузите страницу в поддерживающих настольных и мобильных браузерах и попробуйте прокрутить страницу и выполнить масштабирование пинцетом. В resize и scroll, блок информации перепозиционируется для сохранения того же положения относительно визуальной области просмотра, а показываемая информация о области просмотра и прокрутке обновляется. Также, в resize и scroll мы изменяем цвет блока для обозначения выполнения действия, возвращая его обратно в scrollend.

Вы заметите, что в настольных браузерах значения Window.scrollX и Window.scrollY обновляются при прокрутке окна — положение визуальной области просмотра не изменяется. Однако в мобильных браузерах значения VisualViewport.offsetLeft и VisualViewport.offsetTop обычно обновляются — обычно изменяется визуальная область просмотра, а не положение окна.

Пример HTML представлен ниже. Блок информации представлен элементом <div> с id output.

<p id="instructions">
  Try scrolling around and pinch-zooming to see how the reported values change.
</p>
<div id="output">
  <p id="visual-info"></p>
  <hr />
  <p id="window-info"></p>
</div>

Мы не будем объяснять CSS примера ради краткости — он не важен для понимания демонстрации. Вы можете ознакомиться с ним по ссылке выше.

В JavaScript мы начинаем с получения ссылок на блок информации, который мы будем обновлять при масштабировании и прокрутке страницы, а также на два абзаца внутри него. Первый будет содержать значения VisualViewport.offsetLeft и VisualViewport.offsetTop, а второй — Window.scrollX и Window.scrollY.

const output = document.getElementById("output");
const visualInfo = document.getElementById("visual-info");
const windowInfo = document.getElementById("window-info");

Далее, мы определяем две ключевые функции, которые будут выполняться при срабатывании событий:

• scrollUpdater() будет срабатывать на resize и scroll: эта функция обновляет положение блока информации относительно визуальной области просмотра, запрашивая свойства VisualViewport.offsetTop и VisualViewport.offsetLeft и используя их значения для обновления соответствующих свойств отступов. Также мы меняем цвет фона блока информации, чтобы указать, что происходит какое-то действие, и выполняем функцию updateText() для обновления отображаемых значений.
• Функция scrollEndUpdater() будет срабатывать на scrollend: она возвращает цвет фона блока информации к исходному и выполняет функцию updateText() для отображения последних значений в scrollend.

const scrollUpdater = () => {
  output.style.top = `${visualViewport.offsetTop + 10}px`;
  output.style.left = `${visualViewport.offsetLeft + 10}px`;
  output.style.background = "yellow";
  updateText();
};

const scrollendUpdater = () => {
  output.style.background = "lime";
  updateText();
};

Функция updateText() выглядит следующим образом — она устанавливает HTMLElement.innerText первого абзаца, чтобы показать текущие значения VisualViewport.offsetLeft и VisualViewport.offsetTop, и HTMLElement.innerText второго абзаца, чтобы показать текущие значения Window.scrollX и Window.scrollY. После определения updateText(), мы сразу вызываем её, чтобы блок информации отображался правильно при загрузке страницы.

function updateText() {
  visualInfo.innerText = `Visual viewport left: ${visualViewport.offsetLeft.toFixed(2)}
    top: ${visualViewport.offsetTop.toFixed(2)}`;
  windowInfo.innerText = `Window scrollX: ${window.scrollX.toFixed(2)}
    scrollY: ${window.scrollY.toFixed(2)}`;
}

updateText();

Теперь мы устанавливаем обработчики событий как для визуальной области просмотра, так и для объекта Window, чтобы запускать ключевые функции в соответствующие моменты как для мобильных, так и для настольных устройств:

• Мы устанавливаем обработчики на window, чтобы положение и содержимое блока информации обновлялись при обычных операциях прокрутки окна, например, при прокрутке страницы в настольном браузере.
• Мы устанавливаем обработчики на visualViewport, чтобы положение и содержимое блока информации обновлялись при операциях прокрутки/масштабирования визуальной области просмотра, например, при прокрутке и масштабировании страницы в мобильном браузере.

visualViewport.onresize = scrollUpdater;
visualViewport.onscroll = scrollUpdater;
visualViewport.onscrollend = scrollendUpdater;
window.onresize = scrollUpdater;
window.onscroll = scrollUpdater;
window.onscrollend = scrollendUpdater;

scrollUpdater() будет срабатывать на resize и scroll, а scrollEndUpdater() будет срабатывать на scrollend.