Dodaj manifest aplikacji internetowej

Obsługa przeglądarek

  • 39
  • 79
  • x
  • x

Źródło

Manifest aplikacji internetowej to plik JSON informujący przeglądarkę o tym, jak powinna działać progresywna aplikacja internetowa (PWA) zainstalowana na komputerze lub urządzeniu mobilnym użytkownika. Typowy plik manifestu zawiera przynajmniej:

  • Nazwa aplikacji
  • Ikony, których powinna używać aplikacja
  • Adres URL, który powinien zostać otwarty po uruchomieniu aplikacji

Tworzenie pliku manifestu

Plik manifestu może mieć dowolną nazwę. Powszechnie nazywa się manifest.json i jest wyświetlany z katalogu głównego (katalogu najwyższego poziomu witryny). Specyfikacja sugeruje, że rozszerzenie powinno mieć postać .webmanifest, ale możesz użyć plików JSON, aby pliki manifestu były bardziej czytelne.

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

Kluczowe właściwości pliku manifestu

short_namename

Do pliku manifestu musisz dodać co najmniej jedną z tych właściwości: short_name lub name. Jeśli podasz oba, name będzie używany podczas instalowania aplikacji, a short_name będzie używany na ekranie głównym, w programie uruchamiającym lub w innych miejscach, w których jest ograniczona ilość miejsca.

icons

Gdy użytkownik zainstaluje Twoją progresywną aplikację internetową, możesz zdefiniować zestaw ikon, których przeglądarka będzie używać na ekranie głównym, w Menu z aplikacjami, w przełączniku zadań, na ekranie powitalnym i w innych miejscach.

Właściwość icons to tablica obiektów graficznych. Każdy obiekt musi zawierać src, właściwość sizes i type obrazu. Aby używać ikonach z maskowaniem (na Androidzie nazywanych czasem ikonami adaptacyjnymi), dodaj do właściwości icon wartość "purpose": "any maskable".

W przypadku Chromium musisz udostępnić ikonę o wymiarach co najmniej 192 x 192 piksele oraz ikonę o wymiarach 512 x 512 pikseli. Jeśli możesz podać tylko te 2 rozmiary, Chrome automatycznie skaluje je, by dopasować je do urządzenia. Jeśli wolisz skalować własne ikony i dostosowywać je pod kątem perfekcji, przesyłaj ikony w odstępach co 48 dp.

id

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

start_url

Właściwość start_url jest wymagana. Informuje przeglądarkę o miejscu, w którym powinna uruchomić się aplikacja, i zapobiega jej uruchamianiu na stronie, na której użytkownik w chwili dodania aplikacji 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 będzie chciał zrobić zaraz po otwarciu aplikacji, i umieść ją tam.

background_color

Właściwość background_color jest używana na ekranie powitalnym przy pierwszym uruchomieniu aplikacji na urządzeniu mobilnym.

display

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

Właściwość Sposób działania
fullscreen Otwiera aplikację internetową bez interfejsu przeglądarki i zajmuje cały dostępny obszar wyświetlania.
standalone Otwiera aplikację internetową tak, by wyglądała jak samodzielna aplikacja. Aplikacja działa w osobnym oknie, oddzielnie od przeglądarki i ukrywa standardowe elementy interfejsu przeglądarki, takie jak pasek adresu.
Przykład okna PWA z samodzielnym wyświetlaczem.
Indywidualny interfejs użytkownika.
minimal-ui Ten tryb jest podobny do trybu standalone, ale udostępnia użytkownikowi minimalny zestaw elementów interfejsu do sterowania nawigacją, takich jak przyciski Wstecz i Załaduj ponownie.
Przykład okna PWA z minimalnym wyświetlaczem.
Minimalny interfejs użytkownika.
browser Standardowa przeglądarka.

display_override

Aby wybrać sposób wyświetlania aplikacji internetowej, ustaw w pliku manifestu tryb display w sposób wyjaśniony wcześniej. Przeglądarki nie muszą obsługiwać wszystkich trybów wyświetlania, ale muszą obsługiwać zdefiniowany łańcuch kreacji zastępczych ("fullscreen""standalone""minimal-ui""browser"). Jeśli nie obsługują danego trybu, wraca do następnego trybu wyświetlania w łańcuchu. W rzadkich przypadkach mogą one powodować problemy. Na przykład deweloper nie może zażądać "minimal-ui" bez konieczności ponownego przejścia do trybu wyświetlania "browser", gdy "minimal-ui" nie jest obsługiwany. Obecne zachowanie uniemożliwia też wprowadzanie nowych trybów wyświetlania w sposób zgodny wstecznie, ponieważ nie mają one swojego miejsca w łańcuchu kreacji zastępczych.

Możesz ustawić własną sekwencję kreacji zastępczych za pomocą właściwości display_override, którą przeglądarka uznaje przed właściwością display. Jej wartość to ciąg ciągów znaków należących do podanej kolejności, w których stosuje się pierwszy obsługiwany tryb wyświetlania. Jeśli żadna z nich nie jest obsługiwana, przeglądarka przełącza się na obliczanie pola display. Jeśli nie ma pola display, przeglądarka ignoruje display_override.

Oto przykład użycia właściwości display_override. Szczegóły dotyczące "window-control-overlay" nie należą do 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 ta wartość jest niedostępna, używana jest wartość "minimal-ui", a następnie "standalone" z właściwości display. Jeśli nie będzie dostępny, przeglądarka wróci do standardowego łańcucha kreacji zastępczych.

scope

scope aplikacji to zbiór adresów URL, które przeglądarka uważa za część aplikacji. scope określa strukturę adresów URL obejmującą wszystkie punkty wejścia i wyjścia z aplikacji, a przeglądarka korzysta z niego, aby określić, kiedy użytkownik opuścił aplikację.

Kilka innych uwag na temat scope:

  • Jeśli w pliku manifestu nie podasz elementu scope, domyślnym, domniemanym adresem URL jest scope, ale z nazwą pliku, zapytaniem i fragmentem usunięte.
  • Atrybut scope może być ścieżką względną (../) lub dowolną ścieżką wyższego poziomu (/), która mogłaby zwiększyć pokrycie elementów nawigacyjnych w aplikacji internetowej.
  • start_url musi być w zakresie.
  • Wartość start_url jest określana względem ścieżki określonej w atrybucie scope.
  • Zasób start_url zaczynający się od / będzie zawsze głównym źródłem.

theme_color

theme_color określa kolor paska narzędzi. Możesz go znaleźć w podglądzie aplikacji w opcjach przełączania zadań. Element theme_color powinien być zgodny z kolorem motywu meta określonym w nagłówku dokumentu.

Przykład okna aplikacji PWA z niestandardowym kolorem_motywu.
Przykład okna PWA z niestandardowym parametrem theme_color.

theme_color w zapytaniach o multimedia

Obsługa przeglądarek

  • 93
  • 93
  • 106
  • 15

Źródło

Możesz dostosować właściwość theme_color w zapytaniu o multimedia za pomocą atrybutu media elementu koloru motywu meta. W ten sposób możesz na przykład określić jeden kolor dla trybu jasnego, a inny dla trybu ciemnego. Nie możesz ich jednak zdefiniować w pliku manifestu. Więcej informacji znajdziesz w artykule o problemie z 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

Właściwość shortcuts to tablica obiektów skrótów do aplikacji zapewniających szybki dostęp do najważniejszych zadań w aplikacji. Każdy użytkownik jest słownikiem zawierającym co najmniej name i url.

description

Właściwość description opisuje przeznaczenie aplikacji.

W Chrome maksymalna długość tekstu reklamy na wszystkich platformach to 300 znaków. Jeśli opis będzie dłuższy, przeglądarka skróci go, używając wielokropka. Na Androidzie opis może zawierać maksymalnie 7 wierszy tekstu.

screenshots

Właściwość screenshots to tablica obiektów graficznych reprezentujących aplikację w typowych scenariuszach użytkowania. Każdy obiekt musi zawierać właściwość src, sizes i type obrazu. Właściwość form_factor jest opcjonalna. Możesz ustawić wartość "wide" w przypadku zrzutów ekranu dostępnych tylko na szerokich ekranach, a "narrow" tylko w przypadku wąskich ekranów.

W Chrome obraz musi spełniać te kryteria:

  • Szerokość i wysokość musi wynosić co najmniej 320 i 3840 pikseli.
  • Maksymalny wymiar nie może być większy niż 2,3 raza dłuższy niż długość minimalnego.
  • Wszystkie zrzuty ekranu pasujące do danego formatu muszą mieć ten sam format obrazu.
    • Od Chrome 109 na komputerach wyświetlane są tylko zrzuty ekranu z atrybutem form_factor ustawionym na "wide".
  • Od Chrome 109 na Androidzie zrzuty ekranu z atrybutem form_factor ustawionym na "wide" są ignorowane. Zrzuty ekranu bez funkcji form_factor są nadal wyświetlane na potrzeby zgodności wstecznej.

Chrome na komputerze wyświetla od 1 do 8 zrzutów ekranu, które spełniają te kryteria. Pozostałe są ignorowane.

Chrome na Androidzie wyświetla od 1 do 5 zrzutów ekranu, które spełniają te kryteria. Pozostałe są ignorowane.

Zrzuty ekranu przedstawiające bogatszy interfejs instalacji na komputerze i urządzeniu mobilnym.
Bogaty interfejs instalacji na komputerze i urządzeniu mobilnym.

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

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

Testowanie pliku manifestu

Aby sprawdzić, czy plik manifestu jest prawidłowo skonfigurowany, użyj panelu Plik manifestu w panelu Aplikacja Narzędzi deweloperskich w Chrome.

Panel aplikacji w Narzędziach deweloperskich Chrome z wybraną kartą pliku manifestu.
Przetestuj plik manifestu w Narzędziach deweloperskich.

W tym panelu znajdziesz zrozumiałą dla człowieka wersję wielu właściwości pliku manifestu, co pozwoli Ci sprawdzić, czy wszystkie obrazy wczytują się poprawnie.

Ekrany powitalne na urządzeniach mobilnych

Gdy Twoja aplikacja po raz pierwszy zostanie uruchomiona na urządzeniu mobilnym, może minąć trochę czasu, zanim przeglądarka uruchomi się i zacznie się renderować początkową treść. Zamiast wyświetlać biały ekran, który może sprawić, że aplikacja nie działa, przeglądarka wyświetla ekran powitalny do momentu pierwszego wyrenderowania.

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

Chrome wybiera ikonę, która najlepiej pasuje do rozdzielczości ekranów powitalnych na urządzeniu. Podanie ikon o wymiarach 192 i 512 pikseli wystarczy w większości przypadków, ale możesz dołączyć dodatkowe ikony, aby lepiej je dopasować.

Więcej informacji

Informacje o innych właściwościach, które możesz dodać do pliku manifestu aplikacji internetowej, znajdziesz w dokumentacji pliku manifestu aplikacji internetowej w MDN.