Web manifest: параметры установленного приложения

Прямой ответ

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

{
  "name": "Каталог товаров",
  "short_name": "Каталог",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0b5fff",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

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

Название и значки приложения

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

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

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

Формат значка. Формат и размер указываются явно, поэтому браузер определяет пригодность значка без загрузки файла.

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

Отдельный аспект — маска значка. Часть систем обрезает значок по форме, поэтому безопасная область изображения определяет, остаётся ли содержимое значка видимым после обрезки.

Режим отображения и область действия

Режим отображения определяет оформление окна установленного приложения, поэтому параметр задаёт наличие адресной строки и поведение перехода.

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

Режим с минимальным оформлением. Часть оформления браузера сохраняется, поэтому пользователь видит элементы управления браузера.

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

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

Начальный адрес и проверка документа

Начальный адрес определяет страницу запуска приложения, поэтому значение задаётся относительно области действия.

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

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

Проверка документа. Синтаксис и состав полей проверяются, поэтому ошибка в документе обнаруживается до выпуска.

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

О кэшировании — в статье про service worker; об автономной работе — в статье про офлайн-режим.

Практика: настройка манифеста приложения

1. Задавайте полное и короткое название. Полное используется в списке приложений, короткое — под значком.

2. Добавляйте значки всех требуемых размеров. Отсутствие нужного размера может блокировать предложение установки.

3. Учитывайте безопасную область значка. Содержимое изображения остаётся видимым после обрезки по форме.

4. Выбирайте режим отображения под тип приложения. Режим отдельного окна убирает адресную строку.

5. Задавайте область действия, охватывающую страницы приложения. Переход за пределы области не прерывает автономный режим.

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

7. Проверяйте синтаксис и состав полей документа. Ошибка в манифесте не сообщает о себе на странице.

Рекомендации:

1. Не используйте длинное короткое название. Подпись под значком обрезается, поэтому название читается неполностью.
2. Учитывайте соответствие начального адреса области действия. Расхождение приводит к открытию браузера при запуске.
3. Сопоставляйте режим отображения с назначением приложения. Режим с адресной строкой подходит для содержимого, требующего навигации браузера.
4. Фиксируйте проверку манифеста в процессе разработки. Ошибка документа обнаруживается до выпуска.
5. Пересматриваем поля манифеста при изменении структуры приложения. Новая область требует изменения области действия.

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

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

1. Диагностика. Проверка манифеста показала, что начальный адрес находился за пределами области действия. Браузер открывал адрес вне области, поэтому автономный режим не применялся и отображалась адресная строка.
2. Причина. Область действия была задана уже, чем начальный адрес, поэтому запуск выходил за пределы области приложения.
3. Действия. (а) Привели область действия в соответствие с начальным адресом, чтобы запуск выполнялся в пределах области; (б) проверили, что область охватывает все страницы приложения, чтобы переход не прерывал автономный режим; (в) проверили набор значков и добавили недостающие размеры, чтобы условие представления выполнялось; (г) проверили синтаксис документа, поскольку ошибка не сообщается на странице; (д) установили приложение заново и убедились в открытии отдельного окна.
4. Результат. Приложение открывается в отдельном окне, поскольку начальный адрес находится в пределах области действия.

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

FAQ

Какие поля манифеста обязательны для установки? Название, значки требуемых размеров, начальный адрес и режим отображения. Отсутствие значка может блокировать предложение установки.

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

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

Как обнаружить ошибку в манифесте? Проверкой синтаксиса и состава полей. Браузер не сообщает об ошибке документа на странице, поэтому параметры не применяются молча.

Источники: W3C Web App Manifest, web.dev PWA Checklist, W3C App Manifest — ссылки в шапке.