Манифест веб-приложения — это файл JSON, который сообщает браузеру, как ваше прогрессивное веб-приложение (PWA) должно вести себя при установке на настольный компьютер или мобильное устройство пользователя. Как минимум, типичный файл манифеста включает в себя:
- Название приложения
- Значки, которые должно использовать приложение
- URL-адрес, который должен открываться при запуске приложения.
Создайте файл манифеста
Файл манифеста может иметь любое имя, но обычно он называется manifest.json
и обслуживается из корня (каталога верхнего уровня вашего веб-сайта). The specification suggests the extension should be .webmanifest
, but you might want to use JSON files to make your manifests clearer to read.
Типичный манифест выглядит так:
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-vector.svg",
"type": "image/svg+xml",
"sizes": "512x512"
},
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"id": "/?source=pwa",
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's the weather today?",
"short_name": "Today",
"description": "View weather information for today",
"url": "/today?source=pwa",
"icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
},
{
"name": "How's the weather tomorrow?",
"short_name": "Tomorrow",
"description": "View weather information for tomorrow",
"url": "/tomorrow?source=pwa",
"icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
}
],
"description": "Weather forecast information",
"screenshots": [
{
"src": "/images/screenshot1.png",
"type": "image/png",
"sizes": "540x720",
"form_factor": "narrow"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "720x540",
"form_factor": "wide"
}
]
}
Ключевые свойства манифеста
short_name
и name
В манифесте необходимо указать хотя бы одно из значений short_name
или name
. Если вы укажете и то, и другое, name
будет использоваться при установке приложения, а short_name
будет использоваться на главном экране пользователя, в панели запуска или в других местах, где пространство ограничено.
icons
Когда пользователь устанавливает PWA, вы можете определить набор значков, которые браузер будет использовать на главном экране, средстве запуска приложений, переключателе задач, экране-заставке и в других местах.
Свойство icons
представляет собой массив объектов изображений. Каждый объект должен включать src
, свойство sizes
и type
изображения. Чтобы использовать маскируемые значки , которые в Android иногда называют адаптивными значками, добавьте к свойству icon
"purpose": "any maskable"
.
Для Chromium вы должны предоставить значок размером не менее 192x192 пикселей и значок размером 512x512 пикселей. Если указаны только эти два размера значков, Chrome автоматически масштабирует значки в соответствии с устройством. Если вы предпочитаете масштабировать свои собственные значки и настраивать их до пиксельного совершенства, предоставляйте значки с шагом 48 dp.
id
Свойство id
позволяет явно определить идентификатор, используемый для вашего приложения. Добавление свойства id
в манифест устраняет зависимость от start_url
или местоположения манифеста и дает возможность обновлять их в будущем. Дополнительные сведения см. в разделе Уникальная идентификация PWA с помощью свойства идентификатора манифеста веб-приложения .
start_url
The start_url
is a required property. Он сообщает браузеру, где ваше приложение должно запускаться при запуске, и предотвращает запуск приложения на любой странице, на которой находился пользователь, когда он добавлял ваше приложение на свой главный экран.
Ваш start_url
должен направлять пользователя прямо на ваше приложение, а не на целевую страницу продукта. Подумайте, что пользователь захочет сделать сразу после того, как откроет ваше приложение, и разместите это там.
background_color
Свойство background_color
используется на заставке при первом запуске приложения на мобильном устройстве.
display
Вы можете настроить, какой пользовательский интерфейс браузера будет отображаться при запуске вашего приложения. Например, вы можете скрыть адресную строку и элементы пользовательского интерфейса браузера. Игры даже можно запустить в полноэкранном режиме. The display
property takes one of the following values:
Свойство | Поведение |
---|---|
fullscreen | Открывает веб-приложение без пользовательского интерфейса браузера и занимает всю доступную область отображения. |
standalone | Открывает веб-приложение, которое выглядит как автономное приложение. Приложение запускается в собственном окне, отдельном от браузера, и скрывает стандартные элементы пользовательского интерфейса браузера, такие как адресная строка. |
minimal-ui | Этот режим похож на standalone , но предоставляет пользователю минимальный набор элементов пользовательского интерфейса для управления навигацией, например кнопки «Назад» и «Обновить». |
browser | Стандартный браузер. |
display_override
Чтобы выбрать способ отображения вашего веб-приложения, установите режим display
в его манифесте, как описано ранее . Браузеры не обязаны поддерживать все режимы отображения, но они обязаны поддерживать определенную спецификацией резервную цепочку ( "fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
). Если они не поддерживают данный режим, они возвращаются к следующему режиму отображения в цепочке. В редких случаях эти резервные варианты могут вызвать проблемы. Например, разработчик не может запросить "minimal-ui"
без принудительного возврата в режим отображения "browser"
если "minimal-ui"
не поддерживается. Текущее поведение также делает невозможным введение новых режимов отображения с обратной совместимостью, поскольку им нет места в резервной цепочке.
Вы можете установить собственную резервную последовательность, используя свойство display_override
, которое браузер рассматривает перед свойством display
. Его значение представляет собой последовательность строк, которые рассматриваются в указанном порядке, и применяется первый поддерживаемый режим отображения. If none are supported, the browser falls back to evaluating the display
field. Если поля display
нет, браузер игнорирует display_override
.
Ниже приведен пример использования display_override
. Подробности "window-control-overlay"
выходят за рамки этой страницы.
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
При загрузке этого приложения браузер сначала пытается использовать "window-control-overlay"
. Если это недоступно, он возвращается к "minimal-ui"
, а затем к "standalone"
из свойства display
. Если ни один из них недоступен, браузер возвращается к стандартной резервной цепочке.
scope
scope
действия вашего приложения является набор URL-адресов, которые браузер считает частью вашего приложения. scope
управляет структурой URL-адресов, которая включает все точки входа и выхода в приложение, и браузер использует ее, чтобы определить, когда пользователь покинул приложение.
A few other notes on scope
:
- Если вы не включаете
scope
в свой манифест, то подразумеваемойscope
по умолчанию является начальный URL-адрес, но с удаленным именем файла, запросом и фрагментом. - Атрибут
scope
может представлять собой относительный путь (../
) или любой путь более высокого уровня (/
), который позволит расширить охват навигации в вашем веб-приложении. -
start_url
должен находиться в области видимости. - The
start_url
is relative to the path defined in thescope
attribute. - A
start_url
starting with/
will always be the root of the origin.
theme_color
The theme_color
sets the color of the tool bar, and can be reflected in the app's preview in task switchers. theme_color
должен соответствовать цвету meta
, указанному в заголовке вашего документа.
theme_color
in media queries
Вы можете настроить theme_color
в медиа-запросе, используя атрибут media
элемента цвета meta
. Например, таким образом вы можете определить один цвет для светлого режима и другой для темного. Однако вы не можете определить эти предпочтения в своем манифесте. Дополнительную информацию см. в выпуске w3c/manifest#975 GitHub .
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">
shortcuts
The shortcuts
property is an array of app shortcut objects that provide quick access to key tasks within your app. Каждый член представляет собой словарь, содержащий как минимум name
и url
.
description
Свойство description
описывает цель вашего приложения.
В Chrome максимальная длина описания составляет 300 символов на всех платформах. Если описание длиннее, браузер усекает его, добавляя многоточие. На Android описание также должно содержать не более семи строк текста.
screenshots
Свойство screenshots
представляет собой массив объектов изображений, представляющих ваше приложение в распространенных сценариях использования. Each object must include the src
, a sizes
property, and the type
of image. Свойство form_factor
является необязательным. You can set it either to "wide"
for screenshots applicable to wide screens only or "narrow"
for only narrow screenshots.
В Chrome изображение должно соответствовать следующим критериям:
- Ширина и высота должны быть не менее 320 пикселей и не более 3840 пикселей.
- Максимальный размер не может превышать длину минимального размера более чем в 2,3 раза.
- Все скриншоты, соответствующие соответствующему форм-фактору, должны иметь одинаковое соотношение сторон.
- From Chrome 109, only screenshots with the
form_factor
set to"wide"
are displayed on desktop.
- From Chrome 109, only screenshots with the
- Начиная с Chrome 109, снимки экрана с
form_factor
установленным на"wide"
игнорируются на Android. Снимки экрана безform_factor
по-прежнему отображаются для обратной совместимости.
Chrome на рабочем столе отображает от одного до восьми снимков экрана, соответствующих этим критериям. Остальные игнорируются.
Chrome на Android отображает от одного до пяти снимков экрана, соответствующих этим критериям. Остальные игнорируются.
Добавьте манифест веб-приложения на свои страницы.
After creating the manifest, add a <link>
tag to all the pages of your Progressive Web App. Например:
<link rel="manifest" href="/manifest.json">
Проверьте свой манифест
Чтобы убедиться, что ваш манифест настроен правильно, используйте панель «Манифест» на панели «Приложение» Chrome DevTools.
Эта панель предоставляет удобочитаемую версию многих свойств вашего манифеста и позволяет убедиться, что все изображения загружаются правильно.
Заставки на мобильном телефоне
Когда ваше приложение впервые запускается на мобильном устройстве, может потребоваться некоторое время, прежде чем запустится браузер и начнет отображаться исходный контент. Вместо белого экрана, который может заставить пользователя подумать, что приложение не работает, браузер показывает заставку до первой отрисовки.
Chrome автоматически создает заставку из name
, background_color
и icons
указанных в вашем манифесте. Чтобы создать плавный переход от экрана-заставки к приложению, задайте для background_color
тот же цвет, что и у страницы загрузки.
Chrome выбирает значок, который наиболее точно соответствует разрешению устройства для заставки. В большинстве случаев достаточно значков размером 192 и 512 пикселей, но вы можете предоставить дополнительные значки для лучшего соответствия.
Дальнейшее чтение
Чтобы узнать о других свойствах, которые вы можете добавить в манифест веб-приложения, обратитесь к документации MDN Web App Manifest .