Web App Manifest

Web App Manifest — это JSON-файл, определяющий поведение веб-приложения при установке на устройство пользователя. Он позволяет задавать иконки, цветовую схему, ориентацию экрана и другие параметры, которые делают веб-приложение ближе к нативному по ощущениям.

Структура файла manifest.json

Файл обычно располагается в корне проекта и подключается в HTML через тег:

<link rel="manifest" href="/manifest.json">

Простейший пример manifest.json:

{
  "name": "Preact App",
  "short_name": "Preact",
  "description": "Пример Preact приложения с манифестом",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0d6efd",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
  • name — полное название приложения.
  • short_name — краткое имя, отображаемое на экране устройства.
  • description — описание приложения.
  • start_url — URL, с которого запускается приложение.
  • display — режим отображения (standalone, fullscreen, minimal-ui, browser).
  • background_color — цвет фона при запуске.
  • theme_color — основной цвет интерфейса.
  • icons — массив иконок разных размеров для различных устройств.

Интеграция Web App Manifest с Preact

Preact использует стандартный HTML-шаблон через index.html, поэтому подключение манифеста выполняется привычным образом:

<link rel="manifest" href="%PUBLIC_URL%/manifest.json">

При сборке с помощью Vite или Webpack можно положить manifest.json в папку public для автоматической доступности.

Ключевые свойства для Progressive Web App

  1. display

    • standalone — приложение открывается без браузерных элементов.
    • fullscreen — занимает весь экран.
    • minimal-ui — минимум элементов управления.
    • browser — стандартный браузерный режим.

  2. orientation

    • Устанавливает ориентацию экрана (portrait, landscape).
    • Полезно для мобильных игр и приложений с фиксированным интерфейсом.

  3. scope

    • Определяет область URL, доступную приложению.
    • Пример: "scope": "/app/" ограничит приложение страницами /app/*.

  4. related_applications

    • Ссылки на нативные приложения в магазинах (App Store, Google Play).
    • Позволяет предложить пользователю нативную версию.

  5. prefer_related_applications

    • Если true, браузер рекомендует установить нативное приложение, если оно доступно.

Использование иконок

Иконки должны быть разных размеров для корректного отображения на разных устройствах. Рекомендуется иметь минимум две: 192x192 и 512x512. Форматы: PNG, SVG. Пример:

"icons": [
  {
    "src": "/icons/icon-192.png",
    "sizes": "192x192",
    "type": "image/png"
  },
  {
    "src": "/icons/icon-512.png",
    "sizes": "512x512",
    "type": "image/png"
  }
]

Настройка темы и фона

  • theme_color влияет на цвет панели навигации браузера.
  • background_color используется при запуске приложения до полной загрузки интерфейса.
  • Эти свойства делают Preact-приложение визуально цельным и приближенным к нативному.

Совместимость и проверка

Для проверки корректности манифеста можно использовать:

  • Chrome DevTools → Application → Manifest.
  • Lighthouse Audit для Progressive Web App.

Ошибки обычно возникают из-за:

  • Некорректного формата JSON.
  • Отсутствующих размеров иконок.
  • Несоответствия start_url и scope.

Динамическое изменение manifest.json в Preact

В Preact можно менять theme_color или background_color динамически, используя Jav * aScript:

const metaTheme = document.querySelector('meta[name="theme-color"]');
metaTheme.setAttribute('content', '#ff0000');

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

Итоговое использование в проекте

  • Размещается в public/manifest.json.
  • Подключается через <link rel="manifest">.
  • Содержит минимальные свойства name, short_name, start_url, display, icons.
  • Дополнительные свойства повышают качество PWA: theme_color, background_color, orientation, scope.

Web App Manifest является фундаментальной частью любого Preact-приложения, претендующего на статус Progressive Web App, обеспечивая удобство установки, нативный вид и контроль над поведением на устройстве пользователя.

Оглавление