Отображение содержимого в области заголовка с помощью наложения элементов управления окнами

Статья
05/23/2024

Прогрессивное веб-приложение (PWA), установленное на рабочем столе, может отображать содержимое, где обычно находится строка заголовка, чтобы сделать PWA более собственным с помощью API наложения элементов управления окнами.

API наложения элементов управления окном выполняет следующие действия.

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

Прогрессивное веб-приложение (PWA) может определить, как оно должно отображаться на мобильных платформах, используя элемент отображения в файле манифеста веб-приложения. Тем не менее, для создания иммерсивного, похожего на собственный интерфейс, классические PWA могут использовать другой подход.

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

Приложение PWA в Windows, показывающее, что содержимое приложения отображается под зарезервированной областью заголовка

Отображение содержимого, в котором обычно находится строка заголовка, может помочь PWA чувствовать себя более собственным. Многие классические приложения, такие как Visual Studio Code, Microsoft Teams и Microsoft Edge, уже делают это:

Visual Studio Code отображает содержимое в области заголовка

Включение наложения элементов управления окнами в приложении

Сначала включите функцию наложение элементов управления окном в файле манифеста веб-приложения. Для этого в файле манифеста задайте display_override свойство :

{
  "display_override": ["window-controls-overlay"]
}

См. также:

Переключение строки заголовка

Если включена функция наложения элементов управления окнами, пользователь может выбрать, будет ли строка заголовка или нет, щелкнув переключатель строки заголовка:

Код не может предположить, что наложение оконных элементов управления отображается, так как:

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

Поэтому код должен реагировать на изменения геометрии строки заголовка. Дополнительные сведения см. в статье Реагирование на изменения наложения.

Использование переменных среды CSS для очистки от наложения

Функцию env() CSS можно использовать для доступа к переменным среды, определяемой агентом пользователя.

С помощью функции наложения элементов управления окнами добавляются четыре переменные среды:

Переменная	Описание
`titlebar-area-x`	Расстояние (в `px`) области, обычно занятой строкой заголовка, от левой стороны окна
`titlebar-area-y`	Расстояние (в `px`) области, обычно занятой строкой заголовка, от верхней стороны окна
`titlebar-area-width`	Ширина области заголовка в `px`
`titlebar-area-height`	Высота области заголовка в `px`

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

#title-bar {
  position: fixed;
  left: env(titlebar-area-x, 0);
  top: env(titlebar-area-y, 0);
  height: env(titlebar-area-height, 50px);
  width: env(titlebar-area-width, 100%);
}

При использовании position: fixed; строка заголовка не прокручивается с остальным содержимым и остается выровненной с наложением оконных элементов управления.

Важно знать, где наложение и насколько оно велико. Наложение не всегда может находиться на одной стороне окна; в macOS наложение находится слева, а в Windows наложение — справа. Кроме того, наложение может не всегда иметь одинаковый размер.

Функция env() CSS принимает второй параметр, который полезен для определения положения содержимого приложения при отсутствии или отключении функции наложения элементов управления окнами.

Создание области маркером перетаскивания для окна

Если строка заголовка скрыта, остаются видимыми только элементы управления критически важными для системы окнами (значки Развернуть, Свернуть, Закрыть и Сведения о приложении ). Это означает, что пользователям очень мало места для перемещения окна приложения.

Вы можете использовать -webkit-app-region свойство CSS, чтобы предложить пользователям больше способов перетаскивания приложения. Например, если у приложения есть собственная строка заголовка, вы можете превратить его в маркер перетаскивания окна:

#title-bar {
  position: fixed;
  left: env(titlebar-area-x, 0);
  top: env(titlebar-area-y, 0);
  height: env(titlebar-area-height, 50px);
  width: env(titlebar-area-width, 100%);
  -webkit-app-region: drag;
}

Реагирование на изменения наложения

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

Чтобы прослушать изменения, используйте geometrychange событие в объекте navigator.windowControlsOverlay . Чтобы определить, отображается ли строка заголовка visible , используйте свойство объекта navigator.windowControlsOverlay .

Обратите внимание, что geometrychange активируется очень часто, когда пользователь изменяет размер окна. Чтобы избежать слишком частого выполнения кода с изменением макета и возникновения проблем с производительностью в приложении, используйте debounce функцию, чтобы ограничить количество обработки события. См. раздел Разница между регулированием и развертыванием.

const debounce = (func, wait) => {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
};

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', debounce(e => {
    // Detect if the Window Controls Overlay is visible.
    const isOverlayVisible = navigator.windowControlsOverlay.visible;

    // Get the size and position of the title bar area.
    const titleBarRect = e.titlebarAreaRect;

    console.log(`The overlay is ${isOverlayVisible ? 'visible' : 'hidden'}, the title bar width is ${titleBarRect.width}px`);
  }, 200));
}

Демонстрационная версия приложения

1DIV — это демонстрационное приложение PWA, использующее функцию наложения элементов управления окнами.

В Microsoft Edge откройте демонстрационное приложение 1DIV в новом окне или вкладке.
В адресной строке щелкните доступное приложение. Установите 1DIV ( Откроется диалоговое окно Установка приложения 1DIV .
Нажмите кнопку Установить . Приложение 1DIV откроется в собственном окне с открытым диалоговым окном Установка приложения :

Нажмите кнопку Закрыть (X) диалогового окна. (Или установите или снимите флажки, а затем нажмите кнопку Разрешить .)

Строка заголовка приложения содержит по крайней мере следующие оконные элементы управления:

Значок	Подсказка
	Скрытие строки заголовка
	Параметры и многое другое
	Minimize
	Восстановление
	Close

В строке заголовка нажмите кнопку Скрыть строку заголовка (

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

Верхняя область приложения — это маркер перетаскивания, который позволяет пользователям перемещать окно.

Исходный код этого демонстрационного приложения находится в репозитории 1DIV .

В исходном файле manifest.json объявляется использование приложением функции наложения оконных элементов управления.
Исходный файл app.js использует navigator.windowControlsOverlay объект .
Исходный файл app.css использует titlebar-area-* переменные среды CSS.

Предварительный просмотр пользовательского наложения без установки PWA

В Средствах разработки Microsoft Edge в средстве "Приложение " можно имитировать функцию наложения элементов управления окнами (WCO), не устанавливая сначала PWA и не включая функцию WCO. Моделируя функцию WCO в средствах разработки, вы можете быстрее протестировать изменения кода CSS для области заголовка, чем повторно установить измененный PWA.

Имитированное наложение — это статическое изображение. Значения переменных env(titlebar-area-left)CSS , env(titlebar-area-top), env(titlebar-area-width)и env(titlebar-area-height) задаются в соответствии с выбранной платформой.

См . статью Имитация API наложения элементов управления окнами без установки PWA.

Поделиться через