Dodaj manifest aplikacji internetowej

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Obsługa przeglądarek

• 39
• 79
• x
• 17

Źródło

Manifest aplikacji internetowej to plik JSON informujący przeglądarkę o tym, Progresywna aplikacja internetowa (PWA) powinna działać, gdy zostanie zainstalowana na komputerze użytkownika lub urządzenia mobilnego. Typowy plik manifestu zawiera przynajmniej te elementy:

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

Tworzenie pliku manifestu

Plik manifestu może mieć dowolną nazwę, ale nosi też powszechną nazwę manifest.json i z katalogu głównego (katalogu najwyższego poziomu Twojej witryny). Specyfikacja sugerowane jest rozszerzenie .webmanifest, ale lepiej jest użyć 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"
    }
  ]
}

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

short_name i name

W pliku manifestu musisz podać co najmniej jedną z tych wartości: short_name lub name. Jeśli podasz obydwa, podczas instalowania aplikacji będzie używany parametr name, a pole short_name będzie używane na ekranie głównym, w programie uruchamiającym i w innych miejscach, w których jest wolne miejsce z ograniczeniami.

Uwaga: systemy operacyjne zwykle oczekują, że każde okno aplikacji będzie miało tytuł. Ten tytuł jest wyświetlany na różnych platformach do przełączania okien, takich jak alt+tab, trybu przeglądu i listy półek. W przypadku aplikacji PWA działających w trybie samodzielnym: Chromium dodaje short_name (lub name, jeśli ta funkcja jest niedostępna) do na początku nagłówka <title> dokumentu HTML, aby zapobiec atakom maskowanym, gdy samodzielne aplikacje mogą być mylne, np. z systemem operacyjnym, . Aby zadbać o bezpieczeństwo aplikacji, nie powtarzaj jej nazwy w polu <title> w trybie samodzielnym.

icons

Gdy użytkownik zainstaluje Twoją aplikację PWA, możesz określić zestaw ikon dla przeglądarki. do użycia na ekranie głównym, w menu z aplikacjami, w przełączniku zadań, na ekranie powitalnym i w w innych miejscach.

Właściwość icons to tablica obiektów graficznych. Każdy obiekt musi uwzględnij właściwości src, sizes i type obrazu. Aby użyć funkcji ikony z maskowaniem, nazywane czasami „adaptacyjną”. w Androidzie, dodaj "purpose": "any maskable" do właściwości icon.

W przypadku Chromium musisz dodać ikonę o wymiarach co najmniej 192 x 192 pikseli oraz Ikona pikseli 512 x 512. Jeśli określone są tylko ikony o tych 2 rozmiarach, automatycznie skaluje ikony do rozmiaru urządzenia. Jeśli wolisz dostosować skalę własne ikony i dostosowywać je pod kątem doskonałości pikseli, dodawać kolejne ikony na poziomie 48 dp.

Uwaga: przeglądarki oparte na Chromium obsługują też ikony SVG, które można skalować bez pikselizacji i obsługujące zaawansowane funkcje, reagowania na prefers-color-scheme. Pozostają one jednak w stanie, w jakim były w momencie instalacji, a nie aktualizowane na bieżąco. Aby bezpiecznie używać ikon SVG, zawsze określaj ikonę zrasteryzowaną jako dla przeglądarek, które nie obsługują ikon SVG.

id

Właściwość id umożliwia jawne zdefiniowanie identyfikatora używanego aplikacji. Dodanie właściwości id do pliku manifestu eliminuje zależność start_url lub lokalizację pliku manifestu i umożliwia aktualizację ich użyć w przyszłości. Więcej informacji: Unikalne identyfikowanie aplikacji PWA za pomocą właściwości identyfikatora manifestu aplikacji internetowej.

start_url

Właściwość start_url jest wymagana. Informuje przeglądarkę o tym, aplikacja powinna uruchamiać się w chwili uruchomienia i uniemożliwia jej uruchomienie niezależnie od strony, na której znajdował się użytkownik, gdy dodał aplikację do ekranu głównego.

Element start_url powinien kierować użytkownika bezpośrednio do aplikacji, a nie do produktu strony docelowej. Zastanów się, co użytkownik chce zrobić zaraz po tym, otwórz aplikację i umieść w niej je.

background_color

Właściwość background_color jest używana na ekranie powitalnym, gdy tag aplikacja jest uruchamiana na urządzeniach mobilnych po raz pierwszy.

display

Możesz dostosować interfejs przeglądarki wyświetlany po uruchomieniu aplikacji. Dla: możesz na przykład ukryć pasek adresu i elementy interfejsu przeglądarki. Gry można nawet włączyć na pełnym ekranie. Właściwość display przyjmuje jedną z następujące wartości:

Właściwość	Zachowanie
fullscreen	Otwiera aplikację internetową bez interfejsu przeglądarki i zajmuje wszystkie dostępnego obszaru wyświetlania.
standalone	Otwiera aplikację internetową, która wygląda i działa jak samodzielna aplikacja. Aplikacja działa w osobnym oknie, oddzielonym od przeglądarki i ukrywającym standardowe elementów interfejsu przeglądarki, takich jak pasek adresu. Oddzielny interfejs.
minimal-ui	Ten tryb jest podobny do trybu standalone, ale zapewnia z minimalnym zestawem elementów interfejsu do sterowania nawigacją, takich jak Wstecz i Załaduj ponownie. Minimalistyczny interfejs
browser	Standardowe działanie przeglądarki.

display_override

Aby wybrać sposób wyświetlania aplikacji internetowej, ustaw w pliku manifestu tryb display jako omówiono to wcześniej. Przeglądarki nie muszą obsługiwać wszystkich wyświetlaczy ale są wymagane do obsługi łańcuch kreacji zastępczych zdefiniowany w specyfikacji ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Jeśli nie będą obsługują dany tryb, przechodzą do następnego trybu wyświetlania w łańcuchu. W – w rzadkich przypadkach te wartości zastępcze mogą powodować problemy. Deweloper nie może na przykład: żądanie "minimal-ui" bez wymuszania z powrotem na wyświetlaczu "browser" gdy "minimal-ui" nie jest obsługiwany. Obecne zachowanie sprawia też, że nie da się wprowadzić nowych trybów wyświetlania w sposób zgodny wstecznie, ponieważ nie mają miejsca w łańcuchu kreacji zastępczych.

Możesz ustawić własną sekwencję zastępczą, używając właściwości display_override, które przeglądarka uwzględnia przed właściwością display. Jego wartość to ciąg znaków brany pod uwagę w podanej kolejności, a pierwszy stosowany jest obsługiwany tryb wyświetlania. Jeśli żadna nie jest obsługiwana, przeglądarka przełącza się z powrotem do oceny pola display. Jeśli nie ma pola display, przeglądarka ignoruje display_override.

Poniżej znajdziesz przykład użycia atrybutu display_override. Szczegóły "window-control-overlay" jest poza zakresem dla tej strony.

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

Podczas ładowania tej aplikacji przeglądarka próbuje użyć pliku "window-control-overlay" . Jeśli ta opcja jest niedostępna, przyjmuje wartość "minimal-ui", a następnie "standalone" z usługi display. Jeśli żadna z tych opcji nie jest dostępna, przeglądarka powróci do standardowego łańcucha kreacji zastępczych.

scope

Element scope aplikacji to zbiór adresów URL, które przeglądarka uznaje za część do aplikacji. scope kontroluje strukturę adresów URL, która obejmuje wszystkie wejścia i wyjścia wskazuje aplikację, a przeglądarka na jej podstawie określa, kiedy użytkownik ją opuszcza. aplikację.

Uwaga: jeśli użytkownik kliknie w aplikacji link prowadzący poza scope, link otworzy się i wyrenderuje w istniejącym oknie aplikacji PWA. Jeśli chcesz link do otwarcia w karcie przeglądarki, dodaj target="_blank" do tagu <a>. Wł. Android: linki z atrybutem target="_blank" otwierają się na karcie niestandardowej Chrome.

Kilka innych uwag na temat scope:

• Jeśli w pliku manifestu nie podasz scope, domyślna lokalizacja domniemana scope to początkowy adres URL, ale bez nazwy pliku, zapytania i fragmentu.
• Atrybut scope może być ścieżką względną (../) lub dowolnym wyższym poziomem. (/), która umożliwiłaby zwiększenie zasięgu nawigacji w aplikacji internetowej.
• Element start_url musi należeć do zakresu.
• Wartość start_url odnosi się do ścieżki zdefiniowanej w atrybucie scope.
• Element start_url zaczynający się od / zawsze stanowi pierwiastek punktu początkowego.

theme_color

Pole theme_color ustawia kolor paska narzędzi i może być odzwierciedlony w w podglądzie aplikacji w przełącznikach zadań. Wartość theme_color powinna być taka sama jak wartość Kolor motywu meta został określony 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, korzystając z atrybutu media atrybutu Element koloru motywu meta. Możesz na przykład zdefiniować jeden kolor dla trybu jasnego. a druga do trybu ciemnego. Nie możesz jednak zdefiniować tych atrybutów ustawień w pliku manifestu. Więcej informacji: problem z serwis 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 skrótu do aplikacji obiektów, które zapewniają szybki dostęp do kluczowych zadań w aplikacji. Każdy członek to słownik, który zawiera przynajmniej name i url.

description

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

W Chrome maksymalna długość opisu na wszystkich platformach to 300 znaków. Jeśli opis jest dłuższy, przeglądarka skraca go za pomocą wielokropka. Na Androidzie tekst musi też zawierać maksymalnie 7 wierszy tekstu.

screenshots

Właściwość screenshots to tablica obiektów obrazów reprezentujących Twoją aplikację w typowych scenariuszach użytkowania. Każdy obiekt musi zawierać src, sizes i type obrazu. Właściwość form_factor jest opcjonalna. W przypadku zrzutów ekranu przeznaczonych na szerokie ekrany ustaw wartość "wide". "narrow" tylko w przypadku wąskich zrzutów ekranu.

W Chrome obraz musi spełniać te kryteria:

• Szerokość i wysokość musi wynosić co najmniej 320 pikseli, a maksymalnie 3840 pikseli.
• Maksymalny wymiar nie może być większy niż 2,3 raza długości minimalnej .
• Wszystkie zrzuty ekranu pasujące do odpowiedniego formatu muszą mieć taki sam format format obrazu.
  • Od Chrome 109 tylko zrzuty ekranu z atrybutem form_factor ustawionym na "wide" są wyświetlane na komputerach.
• Od Chrome 109 zrzuty ekranu z atrybutem form_factor ustawionym na "wide" to: ignorowanych na Androidzie. Zrzuty ekranu bez form_factor są nadal wyświetlane w przypadku: wsteczną.

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

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

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

Dodaj do swoich stron plik manifestu aplikacji internetowej

Po utworzeniu pliku manifestu dodaj tag <link> do wszystkich stron Progresywna aplikacja internetowa. Na przykład:

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

Żądanie pliku manifestu jest wysyłane bez danych logowania, nawet jeśli są w tej samej domenie. Jeśli plik manifestu wymaga dane logowania, musisz uwzględnić crossorigin="use-credentials" w tagu manifestu.

Testowanie pliku manifestu

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

Przetestuj plik manifestu w Narzędziach deweloperskich.

W tym panelu znajdziesz czytelną dla człowieka wersję wielu plików manifestu i pozwala sprawdzić, czy wszystkie obrazy się ładują bez obaw.

Ekrany powitalne na urządzeniach mobilnych

Przy pierwszym uruchomieniu aplikacji na urządzeniu mobilnym przeglądarka może potrzebować chwili oraz treść początkową do rozpoczęcia renderowania. Zamiast wyświetlać biały ekran, który może sprawić, że użytkownik uzna, że aplikacja nie działa, pokazuje ekran powitalny do momentu pierwszego wyrenderowania.

Chrome automatycznie tworzy ekran powitalny na podstawie interfejsu name, background_color i icons określone w pliku manifestu. Aby utworzyć płynne z ekranu powitalnego do aplikacji, background_color jest taki sam jak kolor strony wczytywania.

Chrome wybiera ikonę, która najlepiej pasuje do rozdzielczości urządzenia ekranów powitalnych. W większości przypadków wystarczy ikony o wymiarach 192 i 512 pikseli. ale możesz podać dodatkowe ikony, które lepiej pasują.

Więcej informacji

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