Ein Web-App-Manifest ist eine JSON-Datei, die dem Browser mitteilt, wie sich Ihre progressive Web-App (PWA) verhalten soll, wenn sie auf dem Computer oder Mobilgerät des Nutzers installiert ist. Eine typische Manifestdatei enthält mindestens Folgendes:
- Der Name der App
- Die Symbole, die die App verwenden soll
- Die URL, die beim Start der App geöffnet werden soll
Manifestdatei erstellen
Die Manifestdatei kann einen beliebigen Namen haben, heißt aber normalerweise manifest.json
und wird aus dem Stammverzeichnis (das Verzeichnis der obersten Ebene Ihrer Website) bereitgestellt. Laut der Spezifikation sollte die Erweiterung .webmanifest
sein. Möglicherweise möchten Sie JSON-Dateien verwenden, um Ihre Manifeste lesbarer zu machen.
Ein typisches Manifest sieht so aus:
{
"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"
}
]
}
Wichtige Manifestattribute
short_name
und name
Du musst in deinem Manifest entweder short_name
oder name
angeben. Wenn du beides angibst, wird name
verwendet, wenn die App installiert wird, und short_name
wird auf dem Startbildschirm, im Launcher des Nutzers oder an anderen Stellen mit begrenztem Speicherplatz verwendet.
icons
Wenn ein Nutzer Ihre PWA installiert, können Sie eine Reihe von Symbolen definieren, die für den Browser auf dem Startbildschirm, im App Launcher, im Aufgabenwechsel, auf dem Ladebildschirm und an anderen Stellen verwendet werden sollen.
Das Attribut icons
ist ein Array von Bildobjekten. Jedes Objekt muss das src
-Attribut, das sizes
-Attribut und den type
des Bilds enthalten. Wenn du maskierbare Symbole verwenden möchtest, die unter Android manchmal als adaptive Symbole bezeichnet werden, musst du "purpose": "any maskable"
in die Eigenschaft icon
einfügen.
Für Chromium müssen Sie mindestens ein Symbol mit 192 × 192 Pixel und ein Symbol mit 512 × 512 Pixeln angeben. Wenn nur diese beiden Symbolgrößen vorhanden sind, skaliert Chrome die Symbole automatisch an das Gerät. Wenn Sie lieber Ihre eigenen Symbole skalieren und für eine Pixelperfektion anpassen möchten, stellen Sie Symbole in Schritten von 48 dp bereit.
id
Mit dem Attribut id
können Sie die für Ihre Anwendung verwendete ID explizit definieren. Wenn Sie dem Manifest das Attribut id
hinzufügen, ist die Abhängigkeit von start_url
oder vom Speicherort des Manifests entfernt, sodass diese in Zukunft aktualisiert werden können. Weitere Informationen finden Sie unter PWAs mithilfe der Manifest-ID-Eigenschaft der Web-App eindeutig identifizieren.
start_url
Die start_url
ist eine erforderliche Property. Sie teilt dem Browser mit, wo Ihre App beim Start starten soll, und verhindert, dass die App auf der Seite gestartet wird, auf der sich der Nutzer befand, als er die App zu seinem Startbildschirm hinzugefügt hat.
Ihre start_url
sollte den Nutzer direkt zu Ihrer App weiterleiten, nicht auf die Produkt-Landingpage. Überlegen Sie, was Nutzende direkt nach dem Öffnen der App tun möchten, und platzieren Sie sie dort.
background_color
Das Attribut background_color
wird auf dem Ladebildschirm verwendet, wenn die App zum ersten Mal auf einem Mobilgerät gestartet wird.
display
Sie können anpassen, welche Browser-UI beim Starten Ihrer App angezeigt wird. So lassen sich beispielsweise die Adressleiste und die Elemente der Benutzeroberfläche des Browsers ausblenden. Spiele können sogar so gestaltet werden,
dass sie im Vollbildmodus gestartet werden. Das Attribut display
verwendet einen der folgenden Werte:
Property | Behavior |
---|---|
fullscreen |
Öffnet die Web-App ohne Browser-UI und nimmt den gesamten verfügbaren Anzeigebereich ein. |
standalone |
Öffnet die Web-App, damit sie wie eine eigenständige App aussieht. Sie wird in einem eigenen Fenster ausgeführt, das vom Browser getrennt ist, und blendet Standard-UI-Elemente des Browsers wie die Adressleiste aus. |
minimal-ui |
Dieser Modus ähnelt dem standalone , bietet dem Nutzer jedoch eine minimale Anzahl von UI-Elementen zur Steuerung der Navigation, z. B. die Schaltflächen „Zurück“ und „Aktualisieren“.
|
browser |
Eine Standard-Browsererfahrung. |
display_override
Um auszuwählen, wie Ihre Web-App angezeigt wird, legen Sie in ihrem Manifest einen display
-Modus fest, wie zuvor erläutert. Browser müssen nicht alle Anzeigemodi unterstützen, müssen aber die spezifikationsdefinierte Fallback-Kette ("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
) unterstützen. Wenn sie einen bestimmten Modus nicht unterstützen, greifen sie auf den nächsten Anzeigemodus in der Kette zurück. In seltenen Fällen können diese Fallbacks Probleme verursachen. Beispielsweise kann ein Entwickler "minimal-ui"
nicht anfordern, ohne in den "browser"
-Anzeigemodus zurückzukehren, wenn "minimal-ui"
nicht unterstützt wird. Das aktuelle Verhalten macht es auch nicht möglich, neue Anzeigemodi auf abwärtskompatible Weise einzuführen, da sie keinen Platz in der Fallback-Kette haben.
Mit dem Attribut display_override
können Sie eine eigene Fallback-Sequenz festlegen. Dieses Attribut wird im Browser vor dem Attribut display
berücksichtigt. Der Wert ist eine Folge von Strings, die in der aufgeführten Reihenfolge berücksichtigt werden. Es wird der erste unterstützte Anzeigemodus angewendet. Werden keine unterstützt, wertet der Browser das Feld display
aus. Wenn das Feld display
nicht vorhanden ist, wird display_override
im Browser ignoriert.
Im Folgenden finden Sie ein Beispiel für die Verwendung von display_override
. Die Details von "window-control-overlay"
werden auf dieser Seite nicht behandelt.
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
Beim Laden dieser Anwendung versucht der Browser zuerst, "window-control-overlay"
zu verwenden. Sollte dieser nicht verfügbar sein, wird auf "minimal-ui"
und dann auf "standalone"
aus der display
-Property zurückgesetzt. Ist keine dieser Optionen verfügbar, kehrt der Browser zur Standard-Fallback-Kette zurück.
scope
Das scope
-Element Ihrer Anwendung ist die Gruppe von URLs, die der Browser als Teil Ihrer Anwendung betrachtet. scope
steuert die URL-Struktur, die alle Ein- und Ausstiegspunkte der Anwendung enthält. Der Browser bestimmt anhand dieser URL, wann der Nutzer die Anwendung verlassen hat.
Weitere Hinweise zu scope
:
- Wenn du kein
scope
in dein Manifest einfügst, ist die standardmäßig impliziertescope
die Start-URL. Dateiname, Abfrage und Fragment werden jedoch entfernt. - Das Attribut
scope
kann ein relativer Pfad (../
) oder ein beliebiger Pfad auf höherer Ebene (/
) sein, mit dem die Abdeckung der Navigationen in Ihrer Web-App erhöht werden kann. start_url
muss im Bereich enthalten sein.start_url
bezieht sich auf den imscope
-Attribut definierten Pfad.- Eine
start_url
, die mit/
beginnt, ist immer die Stammebene des Ursprungs.
theme_color
Mit theme_color
wird die Farbe der Symbolleiste festgelegt. Sie kann in der Anwendungsvorschau im Task-Wechsler widergespiegelt werden. Der theme_color
sollte der Designfarbe meta
entsprechen, die im Dokumentkopf angegeben ist.
theme_color
in Medienabfragen
Sie können theme_color
in einer Medienabfrage mithilfe des Attributs media
des Designfarbelements meta
anpassen. Auf diese Weise können Sie eine Farbe für den hellen Modus und eine andere für den dunklen Modus definieren. Diese Einstellungen lassen sich jedoch nicht in Ihrem Manifest definieren. Weitere Informationen finden Sie unter GitHub-Problem 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
Das Attribut shortcuts
ist ein Array mit App-Verknüpfungsobjekten, mit denen du schnell auf wichtige Aufgaben in deiner App zugreifen kannst. Jedes Mitglied ist ein Wörterbuch, das mindestens ein name
- und ein url
-Element enthält.
description
Die Eigenschaft description
beschreibt den Zweck Ihrer App.
In Chrome beträgt die maximale Länge der Beschreibung auf allen Plattformen 300 Zeichen. Wenn die Beschreibung länger ist, wird sie vom Browser mit einem Auslassungszeichen gekürzt. Unter Android muss die Beschreibung außerdem maximal sieben Textzeilen enthalten.
screenshots
Das Attribut screenshots
ist ein Array von Bildobjekten, die Ihre App in gängigen Nutzungsszenarien darstellen. Jedes Objekt muss das src
, das Attribut sizes
und das type
des Bildes enthalten. Das Attribut form_factor
ist optional.
Sie können sie entweder auf "wide"
für Screenshots, die nur für Breitbildschirme gelten, oder auf "narrow"
für nur schmale Screenshots festlegen.
In Chrome muss das Bild die folgenden Kriterien erfüllen:
- Die Breite und Höhe müssen zwischen 320 und 3.840 Pixel betragen.
- Die maximale Dimension darf nicht mehr als das 2,3-Fache der Länge der Mindestdimension betragen.
- Alle Screenshots, die mit dem entsprechenden Formfaktor übereinstimmen, müssen dasselbe Seitenverhältnis haben.
- Ab Chrome 109 werden auf dem Computer nur Screenshots angezeigt, für die
form_factor
auf"wide"
gesetzt ist.
- Ab Chrome 109 werden auf dem Computer nur Screenshots angezeigt, für die
- Ab Chrome 109 werden Screenshots, bei denen
form_factor
auf"wide"
gesetzt ist, unter Android ignoriert. Aus Gründen der Abwärtskompatibilität werden trotzdem Screenshots ohneform_factor
angezeigt.
In Chrome auf dem Computer werden mindestens ein und höchstens acht Screenshots angezeigt, die diese Kriterien erfüllen. Alle anderen werden ignoriert.
In Chrome unter Android werden mindestens ein und höchstens fünf Screenshots angezeigt, die diese Kriterien erfüllen. Alle anderen werden ignoriert.
Web-App-Manifest zu Seiten hinzufügen
Nachdem du das Manifest erstellt hast, füge allen Seiten deiner progressiven Web-App ein <link>
-Tag hinzu. Beispiel:
<link rel="manifest" href="/manifest.json">
Manifest testen
Um zu überprüfen, ob Ihr Manifest korrekt eingerichtet ist, verwenden Sie den Bereich Manifest im Bereich Anwendung der Chrome-Entwicklertools.
In diesem Bereich finden Sie eine menschenlesbare Version vieler Eigenschaften Ihres Manifests, mit denen Sie prüfen können, ob alle Images ordnungsgemäß geladen werden.
Ladebildschirme auf Mobilgeräten
Wenn deine App zum ersten Mal auf einem Mobilgerät gestartet wird, kann es einen Moment dauern, bis der Browser gestartet und die ersten Inhalte gerendert werden. Anstelle eines weißen Bildschirms, der den Nutzer denken könnte, dass die App nicht funktioniert, zeigt der Browser bis zum ersten Mal einen Ladebildschirm an.
Chrome erstellt den Ladebildschirm automatisch aus den name
, background_color
und icons
, die in deinem Manifest angegeben sind. Für einen reibungslosen Übergang vom Ladebildschirm zur App muss background_color
dieselbe Farbe wie die Ladeseite haben.
Chrome wählt das Symbol aus, das der Geräteauflösung für die Ladebildschirme am ehesten entspricht. In den meisten Fällen ist die Bereitstellung von 192- oder 512 Pixeln Symbolen ausreichend, Sie können jedoch für eine bessere Übereinstimmung zusätzliche Symbole angeben.
Weitere Informationen
Weitere Informationen zu anderen Attributen, die Sie Ihrem Web-App-Manifest hinzufügen können, finden Sie in der Dokumentation zu MDN Web App Manifest.