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_name
i name
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. |
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.
|
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 jestscope
, 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 atrybuciescope
. - 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.
theme_color
w zapytaniach o multimedia
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 komputerach wyświetlane są tylko zrzuty ekranu z atrybutem
- Od Chrome 109 na Androidzie zrzuty ekranu z atrybutem
form_factor
ustawionym na"wide"
są ignorowane. Zrzuty ekranu bez funkcjiform_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.
Dodaj do swoich stron plik manifestu aplikacji internetowej
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.
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.