Dodaj manifest aplikacji internetowej

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Obsługa przeglądarek

• 39
• 79
• x
• 17

Źródło

Plik manifestu aplikacji internetowej to plik JSON, który informuje przeglądarkę, jak ma się zachowywać progresywna aplikacja internetowa (PWA) po zainstalowaniu na komputerze lub urządzeniu mobilnym użytkownika. Typowy plik manifestu zawiera co najmniej:

• nazwę aplikacji;
• Ikony, których powinna używać aplikacja
• Adres URL, który powinien otwierać się po uruchomieniu aplikacji

Uwaga: użytkownicy mogą zainstalować Twoją aplikację internetową, nawet jeśli nie spełnia ona kryteriów instalacji w Chrome. Więcej informacji znajdziesz w artykule Jak Chrome pomaga użytkownikom instalować przydatne aplikacje.

Tworzenie pliku manifestu

Plik manifestu może mieć dowolną nazwę, ale zwykle jest to manifest.json i jest obsługiwany z katalogu głównego (katalogu najwyższego poziomu Twojej witryny). Specyfikacja sugeruje, że rozszerzenie powinno być .webmanifest, ale możesz użyć plików JSON, aby ułatwić sobie czytanie plików manifestu.

Typowy plik manifestu wygląda tak:

{
  "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"
    }
  ]
}

Najważniejsze właściwości pliku manifestu

short_name i name

W pliku manifestu musisz podać co najmniej 1 atrybut short_name lub name. Jeśli podasz oba te elementy, podczas instalacji aplikacji będzie używany name, a element short_name będzie używany na ekranie głównym użytkownika, w programie uruchamiającym lub w innych miejscach, w których jest ograniczona ilość miejsca.

Uwaga: systemy operacyjne zwykle wymagają tytułu dla każdego okna aplikacji. Ten tytuł jest wyświetlany na różnych powierzchniach przełączania okien, takich jak alt + tab, tryb przeglądu i lista okien na półce. W przypadku PWA działających w trybie samodzielnym Chromium dodaje wartość short_name (lub, jeśli nie jest dostępna, wartość name) do początku <title> dokumentu HTML, aby zapobiec atakom polegającym na przebraniu się za inne aplikacje, w których samodzielne aplikacje mogłyby zostać pomylone na przykład z dialogami systemu operacyjnego. Aby zapewnić bezpieczeństwo aplikacji, nie powtarzaj nazwy aplikacji w polu <title> w trybie samodzielnym.

icons

Gdy użytkownik zainstaluje Twoją PWA, możesz zdefiniować zestaw ikon przeglądarki, które będą wyświetlane na ekranie głównym, w menu aplikacji, przełączniku zadań, na ekranie powitalnym i w innych miejscach.

Właściwość icons to tablica obiektów graficznych. Każdy obiekt musi zawierać właściwości src, sizes i type obrazu. Aby używać ikon z możliwością zamaskowania, które na Androidzie są czasami nazywane adaptacyjnymi, dodaj "purpose": "any maskable" do właściwości icon.

W przypadku Chromium musisz dodać ikonę o wymiarach co najmniej 192 x 192 pikseli i ikonę piksela 512 x 512. Jeśli podasz tylko te 2 rozmiary ikon, Chrome automatycznie je dopasuje do urządzenia. Jeśli wolisz skalować własne ikony i dostosowywać je do pikseli, prześlij je w interwałach 48 dp.

Uwaga: przeglądarki oparte na Chromium obsługują też ikony SVG, które można dowolnie skalować bez utraty jakości, a także funkcje zaawansowane, takie jak reakcja na prefers-color-scheme. Jednak te ikony pozostają w stanie, w jakim były w momencie instalacji, zamiast aktualizować się na bieżąco. Aby bezpiecznie używać ikon SVG, zawsze podawaj ikonę rastrową jako ikonę zapasową dla przeglądarek, które nie obsługują ikon SVG.

id

Właściwość id umożliwia jawne zdefiniowanie identyfikatora używanego w aplikacji. Dodanie do pliku manifestu właściwości id usuwa zależność od start_url lub lokalizacji pliku manifestu i umożliwia ich aktualizację w przyszłości. Więcej informacji znajdziesz w artykule o unikalnym identyfikowaniu aplikacji PWA za pomocą właściwości identyfikatora manifestu aplikacji internetowej.

start_url

Właściwość start_url jest wymagana. Informuje przeglądarkę, gdzie powinna się uruchomić Twoja aplikacja po uruchomieniu i zapobiega uruchamianiu aplikacji na stronie, na której znajdował się użytkownik w momencie dodania jej do ekranu głównego.

start_url powinien kierować użytkownika bezpośrednio do aplikacji, a nie na stronę docelową produktu. Zastanów się, co użytkownik chce zrobić zaraz po otwarciu aplikacji, i umieścić go w odpowiednim miejscu.

background_color

Właściwość background_color jest używana na ekranie powitalnym, gdy aplikacja uruchamia się po raz pierwszy na urządzeniu mobilnym.

display

Możesz dostosować interfejs przeglądarki, który ma być wyświetlany po uruchomieniu aplikacji. Możesz na przykład ukryć pasek adresu i elementy interfejsu przeglądarki. Gry mogą nawet uruchamiać się w trybie pełnoekranowym. Właściwość display może przyjmować jedną z tych wartości:

Właściwość	Zachowanie
fullscreen	Otwiera aplikację internetową bez interfejsu przeglądarki i zajmuje całą dostępną powierzchnię wyświetlacza.
standalone	Otwiera aplikację internetową, aby wyglądała i działała jak samodzielna aplikacja. Aplikacja działa w oddzielnym oknie, oddzielonym od przeglądarki, i ukrywa standardowe elementy interfejsu przeglądarki, takie jak pasek adresu. Samodzielny interfejs użytkownika.
minimal-ui	Ten tryb jest podobny do standalone, ale zapewnia użytkownikowi minimalny zestaw elementów interfejsu do sterowania nawigacją, takich jak przyciski Wstecz i Odśwież. Minimalny interfejs użytkownika.
browser	Standardowe działanie przeglądarki.

display_override

Aby wybrać sposób wyświetlania aplikacji internetowej, w jej pliku manifestu ustaw tryb display, jak omówiliśmy to wcześniej. Przeglądarki nie muszą obsługiwać wszystkich trybów wyświetlania, ale muszą obsługiwać łańcuch definiowany przez specyfikację ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Jeśli nie obsługują danego trybu, przechodzą do następnego trybu wyświetlania w łańcuchu. W rzadkich przypadkach te alternatywne rozwiązania mogą powodować problemy. Na przykład deweloper nie może poprosić o "minimal-ui", jeśli nie jest to możliwe w trybie wyświetlania "browser", gdy "minimal-ui" nie jest obsługiwane. Obecne działanie uniemożliwia też wprowadzenie nowych trybów wyświetlania w sposób zgodny z wstecz, ponieważ nie mają one miejsca w łańcuchu zastępczym.

Możesz ustawić własną sekwencję zastępczą za pomocą właściwości display_override, którą przeglądarka bierze pod uwagę przed właściwością display. Jego wartość to sekwencja ciągów znaków, które są rozpatrywane w podanej kolejności, a pierwszy obsługiwany tryb wyświetlania jest stosowany. Jeśli żadna z nich nie jest obsługiwana, przeglądarka przechodzi do sprawdzania pola display. Jeśli pole display jest puste, przeglądarka ignoruje display_override.

Poniżej znajdziesz przykład użycia atrybutu display_override. Szczegóły dotyczące "window-control-overlay" wykraczają poza zakres tej strony.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

Podczas wczytywania tej aplikacji przeglądarka najpierw próbuje użyć "window-control-overlay". Jeśli nie jest dostępna, przyjmuje wartość "minimal-ui", a następnie "standalone" z właściwości display. Jeśli żaden z nich nie jest dostępny, przeglądarka wraca do standardowego łańcucha zastępczego.

scope

scope aplikacji to zbiór adresów URL, które przeglądarka uznaje za część aplikacji. scope kontroluje strukturę adresów URL, która obejmuje wszystkie punkty wejścia i wyjścia z aplikacji. Przeglądarka używa jej do określania, kiedy użytkownik opuścił aplikację.

Uwaga: jeśli użytkownik kliknie w aplikacji link, który prowadzi poza aplikację scope, link otworzy się i zostanie wyrenderowany w bieżącym oknie PWA. Jeśli chcesz, aby link otwierał się w karcie przeglądarki, dodaj tag target="_blank" do tagu <a>. Na Androidzie linki z target="_blank" otwierają się w karcie niestandardowej Chrome.

Kilka innych uwag na temat scope:

• Jeśli nie uwzględnisz atrybutu scope w pliku manifestu, domyślnie zostanie użyty domyślny atrybut scope, czyli URL początkowy bez nazwy pliku, zapytania i fragmentu.
• Atrybut scope może być ścieżką względną (../) lub ścieżką o wyższym poziomie (/), która pozwoli zwiększyć zasięg nawigacji w aplikacji internetowej.
• start_url musi znajdować się w zakresie.
• Wartość start_url jest względna względem ścieżki zdefiniowanej w atrybucie scope.
• start_url rozpoczynający się od / będzie zawsze korzeniami źródła.

theme_color

Wartość theme_color określa kolor paska narzędzi i może być widoczna w podglądzie aplikacji w przełączniku zadań. Kolor theme_color powinien być zgodny z kolorem motywu meta określonym w nagłówku dokumentu.

Przykład okna PWA z niestandardowym theme_color.

theme_color w zapytaniach o media

Obsługa przeglądarek

• 93
• 93
• 106
• 15

Źródło

Możesz dostosować theme_color w zapytaniu o media, używając atrybutu media elementu koloru motywu meta. W ten sposób możesz na przykład zdefiniować jeden kolor dla trybu jasnego, a inny dla trybu ciemnego. Nie możesz jednak definiować tych preferencji w pliku manifestu. Więcej informacji znajdziesz w artykule o problemie z GitHubem dotyczącym w3c/manifest#975.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

Właściwość shortcuts to tablica obiektów skrótów aplikacji, które zapewniają szybki dostęp do kluczowych zadań w aplikacji. Każdy element jest słownikiem zawierającym co najmniej element name i url.

description

Właściwość description określa cel aplikacji.

W Chrome maksymalna długość opisu na wszystkich platformach to 300 znaków. Jeśli opis jest dłuższy, przeglądarka skróci go za pomocą wielokropka. Na Androidzie opis może się składać z maksymalnie 7 wierszy tekstu.

screenshots

Właściwość screenshots to tablica obiektów obrazów reprezentujących Twoją aplikację w popularnych scenariuszach użycia. Każdy obiekt musi zawierać właściwości src, sizes i type obrazu. Właściwość form_factor jest opcjonalna. Możesz ustawić wartość "wide", aby zrzuty ekranu były wyświetlane tylko na szerokich ekranach, lub "narrow", aby były wyświetlane tylko na wąskich ekranach.

W Chrome obraz musi spełniać te kryteria:

• Szerokość i wysokość musi wynosić co najmniej 320 pikseli, a maksymalnie 3840 pikseli.
• Maksymalny rozmiar nie może być większy niż 2,3-krotna długość rozmiaru minimalnego.
• Wszystkie zrzuty ekranu odpowiadające odpowiedniemu formatowi muszą mieć ten sam format obrazu.
  • Od wersji 109 Chrome na komputerach wyświetlane są tylko zrzuty ekranu, w których opcja form_factor jest ustawiona na "wide".
• Od wersji 109 Chrome zrzuty ekranu z ustawieniami form_factor na "wide" są ignorowane na Androidzie. Zrzuty ekranu bez form_factor są nadal wyświetlane ze względu na zgodność wsteczną.

Chrome na komputerach wyświetla co najmniej 1 i maksymalnie 8 zrzutów ekranu, które spełniają te kryteria. Pozostałe są ignorowane.

Chrome na Androidzie wyświetla co najmniej 1 i maksymalnie 5 zrzutów ekranu spełniających te kryteria. Pozostałe są ignorowane.

Bogatszy interfejs użytkownika instalacji na komputerach i urządzeniach mobilnych.

Dodawanie pliku manifestu aplikacji internetowej do stron

Po utworzeniu pliku manifestu dodaj tag <link> do wszystkich stron swojej progresywnej aplikacji internetowej. Przykład:

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

Żądanie pliku manifestu jest wysyłane bez poświadczeń, nawet jeśli znajduje się w tej samej domenie. Jeśli manifest wymaga danych logowania, musisz umieścić tag crossorigin="use-credentials" w pliku manifestu.

Testowanie pliku manifestu

Aby sprawdzić, czy manifest jest prawidłowo skonfigurowany, użyj panelu Manifest w panelu Aplikacja w Narzędziach deweloperskich Chrome.

Testuj plik manifestu w Narzędziach deweloperskich.

W tym panelu znajdziesz czytelną dla człowieka wersję wielu właściwości pliku manifestu. Możesz też sprawdzić, czy wszystkie obrazy wczytują się prawidłowo.

Ekrany powitalne na urządzeniach mobilnych

Gdy aplikacja uruchamia się po raz pierwszy na urządzeniu mobilnym, może minąć chwila, zanim przeglądarka się uruchomi i zacznie renderować początkową treść. Zamiast wyświetlać biały ekran, który może sprawić, że użytkownik pomyśli, że aplikacja nie działa, przeglądarka wyświetla ekran powitalny do momentu pierwszej aktualizacji.

Chrome automatycznie tworzy ekran powitalny na podstawie plików name, background_color i icons określonych w pliku manifestu. Aby zapewnić płynne przejście z ekranu powitalnego do aplikacji, nadaj elementowi background_color ten sam kolor co stronie wczytywania.

Chrome wybiera ikonę, która najbardziej pasuje do rozdzielczości urządzenia, na którym wyświetla się ekran powitalny. W większości przypadków wystarczy przesłanie ikon o wymiarach 192 pikseli i 512 pikseli, ale możesz też przesłać dodatkowe ikony, aby uzyskać lepsze dopasowanie.

Więcej informacji

Więcej informacji o innych właściwościach, które możesz dodać do pliku manifestu aplikacji internetowej, znajdziesz w dokumentacji MDN na temat pliku manifestu aplikacji internetowej.