Манифест веб-приложения — это создаваемый вами файл, который сообщает браузеру, как вы хотите, чтобы ваш веб-контент отображался в виде приложения в операционной системе. Манифест может включать базовую информацию, такую как имя приложения, значок и цвет темы; расширенные настройки, такие как желаемая ориентация и ярлыки приложений; и метаданные каталога, такие как снимки экрана.
Каждый PWA должен включать в себя один манифест для каждого приложения, который обычно размещается в корневой папке и связан со всеми HTML-страницами, с которых можно установить PWA. Его официальное расширение — .webmanifest
, поэтому вы можете назвать свой манифест примерно так: app.webmanifest
.
Добавление манифеста веб-приложения в PWA
Чтобы создать манифест веб-приложения, сначала создайте текстовый файл с объектом JSON, содержащим как минимум поле name
со строковым значением:
приложение.вебманифест:
{
"name": "My First Application"
}
Но создания файла недостаточно: браузеру также необходимо знать, что он существует.
Ссылка на ваш манифест
Чтобы браузер знал о манифесте вашего веб-приложения, вам необходимо связать его с вашим PWA с помощью HTML-элемента <link>
и атрибута rel
, установленного для manifest
на всех HTML-страницах вашего PWA. Это похоже на то, как вы связываете таблицу стилей CSS с документом.
индекс.html:
<html lang="en">
<title>This is my first PWA</title>
<link rel="manifest" href="/app.webmanifest">
Отладка манифеста
Чтобы убедиться, что манифест настроен правильно, вы можете использовать Inspector в Firefox и DevTools в каждом браузере на базе Chromium.
Для браузеров Chromium
В инструментах разработчика
- На левой панели в разделе «Приложение» выберите «Манифест» .
- Проверьте поля манифеста, проанализированные браузером.
Для Firefox
- Откройте Инспектор.
- Перейдите на вкладку «Приложение».
- Выберите параметр «Манифест» на левой панели.
- Проверьте поля манифеста, проанализированные браузером.
Проектирование вашего опыта PWA
Теперь, когда ваш PWA подключен к своему манифесту, пришло время заполнить остальные поля, чтобы определить удобство для ваших пользователей.
Основные поля
Первый набор полей представляет основную информацию о вашем PWA. Они используются для создания значка и окна установленного PWA и определения способа его запуска. Они есть:
-
name
- Полное имя вашего PWA. Он появится вместе со значком на главном экране, панели запуска, доке или меню операционной системы.
-
short_name
- Необязательно, более короткое имя вашего PWA, используемое, когда недостаточно места для отображения полного значения поля
name
. Не превышайте 12 символов, чтобы свести к минимуму возможность усечения. -
icons
- Массив объектов-значков с полями
src
,type
,sizes
и дополнительнымиpurpose
, описывающими, какие изображения должны представлять PWA. -
start_url
- URL-адрес, который PWA должен загрузить, когда пользователь запускает его с установленного значка. Рекомендуется указывать абсолютный путь, поэтому, если домашняя страница вашего PWA является корнем вашего сайта, вы можете установить для этого параметра значение «/», чтобы открывать ее при запуске приложения. Если вы не укажете начальный URL-адрес, браузер может использовать в качестве начального URL-адрес, с которого было установлено PWA. Это может быть глубокая ссылка, например подробная информация о продукте вместо главного экрана.
-
display
- Один из
fullscreen
,standalone
,minimal-ui
илиbrowser
, описывающий, как ОС должна отображать окно PWA. Подробнее о различных режимах отображения вы можете прочитать в главе «Дизайн приложения» . В большинстве случаев использования реализуютсяstandalone
. -
id
- Строка, которая однозначно идентифицирует это PWA среди других, которые могут размещаться в том же источнике. Если он не установлен,
start_url
будет использоваться в качестве резервного значения. Имейте в виду, что, изменяяstart_url
в будущем (например, при изменении значения строки запроса), вы можете лишить браузер возможности обнаруживать, что PWA уже установлено.
Иконки
Значок вашего PWA — это его визуальная идентичность на устройствах ваших пользователей после установки, поэтому важно определить хотя бы один. Поскольку свойство icons
представляет собой коллекцию объектов значков, вы можете определить несколько значков в разных форматах, чтобы обеспечить удобство работы со значками для ваших пользователей. Каждый браузер выберет один или несколько значков в зависимости от своих потребностей и операционной системы, в которой он установлен, значки будут ближе к необходимым спецификациям.
Если вам нужно выбрать только один размер значка, он должен быть 512 на 512 пикселей. Однако рекомендуется предоставить изображения большего размера, включая изображения размером 192 на 192, 384 на 384 и 1024 на 1024 пикселя.
"icons": [
{
"src": "icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
}
]
Если вы не предоставите значок или значки не соответствуют рекомендуемым размерам, на некоторых платформах вы не пройдете критерии установки . На других платформах значок будет создан автоматически, например, на основе снимка экрана PWA или с использованием общего значка.
Маскируемые значки
Некоторые операционные системы, такие как Android, адаптируют значки к разным размерам и формам. Например, в Android 12 разные производители или настройки могут менять форму значков с кругов на квадраты или на квадраты с закругленными углами. Для поддержки таких адаптивных значков вы можете предоставить маскируемый значок, используя поле purpose
.
Для этого предоставьте квадратный файл изображения, основной значок которого находится в «безопасной зоне» — круге с центром в значке и радиусом 40 процентов ширины значка. (См. изображение ниже.) Устройства, поддерживающие маскируемые значки, будут маскировать ваш значок по мере необходимости.
Вот пример маскируемого значка, представленного в нескольких часто используемых формах:
Если на следующем изображении вы используете значок слева в качестве маскируемого значка, вы получите плохие результаты на устройствах при применении маски формы.
Это изображение можно было бы использовать с дополнительными отступами.
Маскируемые значки должны иметь размер не менее 512 на 512 пикселей. Создав один из них, вы можете добавить его в свою коллекцию icons
, чтобы улучшить взаимодействие с поддерживаемыми устройствами:
"icons": [
{
"src": "/icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "/icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
},
{
"src": "/icons/512-maskable.png",
"type": "image/png",
"sizes": "512x512",
"purpose": "maskable"
},
]
В большинстве случаев, если маскируемый значок отображается плохо, его можно улучшить, добавив дополнительные поля. Maskable.app — это бесплатный онлайн-инструмент для тестирования и создания маскируемой версии вашей иконки.
Рекомендуемые поля
Следующий набор полей, который следует включить, — это те, которые улучшат взаимодействие с пользователем, даже если они не обязательны для установки.
-
theme_color
- Цвет приложения по умолчанию, иногда влияющий на то, как ОС отображает сайт (например, цвет окна и строки заголовка на рабочем столе или цвет строки состояния на мобильных устройствах). Этот цвет может быть переопределен элементом HTML
theme-color
<meta>
. -
background_color
- Цвет заполнителя, который будет отображаться в фоновом режиме приложения перед загрузкой его таблицы стилей. Safari на iOS и iPadOS, а также большинство настольных браузеров в настоящее время игнорируют это поле.
-
scope
- Изменяет область навигации PWA, позволяя вам определить, что отображается, а что нет в окне установленного приложения. Например, если вы ссылаетесь на страницу за пределами области действия, она будет отображаться в браузере приложения, а не в окне PWA. Однако это не изменит область действия вашего сервис-воркера.
На следующем изображении показано, как поле theme_color
используется для строки заголовка на настольном устройстве при установке PWA.
При определении цветов в манифесте, например, в theme_color
и background_color
, вы должны использовать цвета с именами CSS, например, salmon
или orange
, цвета RGB, например #FF5500
, или цветовые функции без прозрачности, такие как rgb()
или hsl()
. Дополнительную информацию можно найти в главе «Дизайн приложения» .
Попробуйте это
Заставки
На некоторых устройствах статическое изображение отображается во время загрузки PWA, чтобы обеспечить немедленную обратную связь с пользователем.
Android использует значения theme_color
, background_color
и icon
для создания заставки.
Когда вы устанавливаете PWA на Android, устройство создает заставку с информацией, полученной из вашего манифеста, как показано на следующей схеме.
С другой стороны, Safari на iOS и iPadOS не использует манифест веб-приложения для создания заставок. Вместо этого они используют изображение, связанное с собственным элементом <link>
аналогично тому, как они обрабатывают значки. Более подробную информацию можно найти в главе «Улучшение» .
Расширенные поля
Следующий набор полей предлагает дополнительную информацию о вашем PWA. Все они не являются обязательными.
-
lang
- Языковой тег, определяющий основной язык значений манифеста, например
en
для английского,pt-BR
для бразильского португальского языка илиin
для хинди. -
dir
- Направление отображения полей манифеста с поддержкой направления (таких как
name
,short_name
description
). Допустимые значения:auto
,ltr
(слева направо) иrtl
(справа налево). -
orientation
- Желаемая ориентация приложения после установки. Игра может настроить запрос только альбомной ориентации. Принимаются несколько значений , но если они включены, то обычно это явно
portrait
илиlandscape
.
Рекламные поля
Четвертый набор полей позволяет вам предоставлять рекламную информацию о вашем PWA, например, в процессах установки, списках и результатах поиска.
-
description
- Объяснение того, что делает PWA.
-
screenshots
- Массив объектов скриншотов с
src
,type
иsizes
(аналогично объектуicons
), предназначенный для демонстрации PWA. Ограничений по размеру нет. -
categories
- Массив категорий, к которым должно принадлежать PWA, чтобы их можно было использовать в качестве подсказок для списков, при необходимости из списка известных категорий . Эти значения обычно пишутся строчными буквами.
-
iarc_rating_id
- Код сертификации Международной коалиции возрастных рейтингов для PWA, если он у вас есть. Он предназначен для определения того, для какого возраста подходит ваше PWA.
Вы можете увидеть эти рекламные поля в действии уже сегодня. Например, на Android, если PWA можно установить и вы указали значения хотя бы для полей description
и screenshots
, диалоговое окно установки трансформируется из простой информационной панели «Добавить на главный экран» в более богатое диалоговое окно установки, подобное один из магазина приложений.
На Android вы можете получить более приятный пользовательский интерфейс установки, если укажете значения в рекламных полях, как вы можете увидеть в следующем видео.
Посмотрите эти рекламные поля в действии:
Поля возможностей
Наконец, существует ряд полей, связанных с различными возможностями, которые ваш PWA может использовать в поддерживаемых браузерах, например поля shortcuts
, share_target
, display_overrides
, о которых мы рассказываем в главе «Возможности» . Существуют также поля, такие как related_apps
и prefer_related_apps
(дополнительную информацию см. в главе «Обнаружение» ) для подключения вашего PWA к установленным приложениям, часто из магазина приложений.
В будущем может появиться множество новых полей, поскольку браузеры добавят больше возможностей в Progressive Web Apps.