Aggiungi un file manifest di un'app web

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Un file manifest dell'app web è un file JSON che indica al browser come Il comportamento delle app web progressive (PWA) è necessario quando è installata sul desktop dell'utente oppure dispositivo mobile. Un tipico file manifest include almeno:

• Il nome dell'app
• Le icone che l'app dovrebbe utilizzare
• L'URL che dovrebbe essere aperto all'avvio dell'app

Creare il file manifest

Il file manifest può avere qualsiasi nome, ma è comunemente chiamato manifest.json e pubblicati dalla directory principale (la directory di primo livello del tuo sito web). Le specifiche suggerisce che l'estensione dovrebbe essere .webmanifest, ma potresti voler usare JSON per rendere i tuoi manifest più chiari da leggere.

Un tipico file manifest ha il seguente aspetto:

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

Proprietà manifest principali

short_name e name

Devi fornire almeno uno dei valori short_name o name nel file manifest. Se fornisci entrambi, name viene usato quando l'app è installata e short_name è utilizzata nella schermata Home dell'utente, in Avvio app o in altre posizioni in cui si trova limitato.

icons

Quando un utente installa la tua PWA, puoi definire un insieme di icone per il browser. da usare nella schermata Home, in Avvio applicazioni, nel selettore di attività, nella schermata iniziale e in altri posti.

La proprietà icons è un array di oggetti immagine. Ogni oggetto deve includi src, una proprietà sizes e type dell'immagine. Per utilizzare icone mascherabili, a volte chiamate adattive su Android, aggiungi "purpose": "any maskable" alla proprietà icon.

Per Chromium, devi fornire un'icona di almeno 192 x 192 pixel e un Icona pixel 512 x 512. Se vengono fornite solo queste due dimensioni di icone, Chrome ridimensiona automaticamente le icone per adattarle al dispositivo. Se preferisci scalare icone personalizzate e regolarle per ottenere un pixel perfetto, fornire icone in incrementi di 48 dp.

id

La proprietà id ti consente di definire esplicitamente l'identificatore utilizzato per un'applicazione. L'aggiunta della proprietà id al manifest rimuove la dipendenza da start_url o la posizione del manifest e consente di aggiornare in futuro. Per ulteriori informazioni, vedi Identificare in modo univoco le PWA con la proprietà ID manifest dell'app web.

start_url

start_url è una proprietà obbligatoria. Indica al browser dove si trova l'app dovrebbe avviarsi all'avvio e ne impedisce l'avvio la pagina visualizzata dall'utente quando ha aggiunto la tua app alla schermata Home.

start_url deve indirizzare l'utente direttamente alla tua app, non a un prodotto pagina di destinazione. Pensa a ciò che l'utente vorrà fare subito dopo apri l'app e posizionali lì.

background_color

La proprietà background_color viene utilizzata nella schermata iniziale quando la proprietà viene lanciata per la prima volta su un dispositivo mobile.

display

Puoi personalizzare quale UI del browser mostrare all'avvio dell'app. Per Ad esempio, puoi nascondere la barra degli indirizzi e gli elementi dell'interfaccia utente del browser. Partite e possono essere lanciati a schermo intero. La proprietà display utilizza uno dei seguenti i seguenti valori:

Proprietà	Comportamento
fullscreen	Apre l'app web senza UI del browser e occupa tutte le disponibile.
standalone	Apre l'app web in modo che abbia l'aspetto e il design di un'app autonoma. L'app viene eseguita in una propria finestra, separata dal browser, e nasconde elementi dell'interfaccia utente del browser, come la barra degli indirizzi.
minimal-ui	Questa modalità è simile a standalone, ma fornisce il un utente con un insieme minimo di elementi UI per controllare la navigazione, come i pulsanti Indietro e Ricarica.
browser	Un'esperienza browser standard.

display_override

Per scegliere la modalità di visualizzazione della tua app web, imposta una modalità display nel file manifest come come spiegato in precedenza. I browser non sono tenuti a supportare tutti i formati display ma sono necessarie per supportare il catena di fallback definita dalle specifiche ("fullscreen" → "standalone" → "minimal-ui" → "browser"). In caso contrario una determinata modalità, passano alla modalità di visualizzazione successiva nella catena. Nella rari casi, questi fallback possono causare problemi. Ad esempio, uno sviluppatore non può richiedi "minimal-ui" senza essere forzati di nuovo a visualizzare "browser" quando "minimal-ui" non è supportato. Il comportamento attuale rende impossibile introdurre nuove modalità di visualizzazione compatibili con le versioni precedenti, perché non è presente nella catena di riserva.

Puoi impostare una sequenza di fallback personalizzata utilizzando la proprietà display_override, che il browser prende in considerazione prima della proprietà display. Il suo valore è un sequenza di stringhe considerate nell'ordine elencato e la prima viene applicata la modalità di visualizzazione supportata. Se nessuno è supportato, il browser esegue un ripristino alla valutazione del campo display. Se non è presente un campo display, il browser ignora display_override.

Di seguito è riportato un esempio di come utilizzare display_override. I dettagli di "window-control-overlay" non rientra nell'ambito per questa pagina.

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

Durante il caricamento di questa app, il browser prova a utilizzare "window-control-overlay" per prima cosa. Se non è disponibile, torna a "minimal-ui" e poi a "standalone" dalla proprietà display. Se nessuna di queste opzioni è disponibile, browser torna alla catena di fallback standard.

scope

Il scope della tua app è l'insieme di URL che il browser considera parte di la tua app. scope controlla la struttura dell'URL che include tutte le voci di ingresso e di uscita punta all'app che il browser la utilizza per determinare quando l'utente ha abbandonato l'app.

Alcune altre note relative a scope:

• Se non includi un scope nel file manifest, verrà usato il valore predefinito scope è l'URL di inizio, ma senza nome file, query e frammento.
• L'attributo scope può essere un percorso relativo (../) o un livello superiore (/) che consentirebbe un aumento della copertura delle navigazioni nell'app web.
• start_url deve rientrare nell'ambito.
• Il valore start_url è relativo al percorso definito nell'attributo scope.
• Un start_url che inizia con / sarà sempre la radice dell'origine.

theme_color

theme_color imposta il colore della barra degli strumenti e può essere riflesso in l'anteprima dell'app nei commutatori delle attività. Il valore theme_color deve corrispondere al valore Colore tema meta specificato nell'intestazione del documento.

theme_color nelle query supporti

Puoi modificare theme_color in una query multimediale utilizzando l'attributo media del Elemento colore tema meta. Ad esempio, puoi definire un colore per la modalità Luce e un'altra per la modalità Buio in questo modo. Tuttavia, non puoi definirli preferenze nel tuo file manifest. Per ulteriori informazioni, vedi il problema di GitHub 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

La proprietà shortcuts è un array di scorciatoia dell'app che forniscono un accesso rapido alle attività chiave all'interno dell'app. Ogni membro è un dizionario che contiene almeno name e url.

description

La proprietà description descrive lo scopo della tua app.

In Chrome, la lunghezza massima della descrizione è di 300 caratteri su tutte le piattaforme. Se la descrizione è più lunga, il browser la tronca con una i puntini di sospensione. Su Android, la descrizione deve inoltre contenere al massimo sette righe di testo.

screenshots

La proprietà screenshots è un array di oggetti immagine che rappresentano la tua app in scenari di utilizzo comuni. Ogni oggetto deve includere src e sizes e il type dell'immagine. La proprietà form_factor è facoltativa. Puoi impostare il valore su "wide" per gli screenshot applicabili agli schermi ampi o "narrow" solo per screenshot di dimensioni ridotte.

In Chrome, l'immagine deve soddisfare i seguenti criteri:

• La larghezza e l'altezza devono essere da almeno 320 px a 3840 px.
• La dimensione massima non può essere più di 2,3 volte la lunghezza del valore minimo .
• Tutti gli screenshot corrispondenti al fattore di forma appropriato devono avere lo stesso proporzioni.
  • Da Chrome 109, solo gli screenshot con form_factor impostato su "wide" sono visualizzate sui computer.
• In Chrome 109, gli screenshot con l'opzione form_factor impostata su "wide" vengono visualizzate ignorato su Android. Gli screenshot senza form_factor vengono comunque visualizzati per la compatibilità con le versioni precedenti.

Chrome su computer mostra almeno uno screenshot e al massimo otto screenshot che soddisfano questi criteri. Le altre vengono ignorate.

Chrome su Android mostra almeno uno e massimo cinque screenshot che soddisfano questi criteri. Le altre vengono ignorate.

Aggiungi il manifest dell'app web alle tue pagine

Dopo aver creato il file manifest, aggiungi un tag <link> a tutte le pagine del tuo App web progressiva. Ad esempio:

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

Testare il manifest

Per verificare che il file manifest sia configurato correttamente, utilizza il riquadro Manifest nel Riquadro Applicazione di Chrome DevTools.

Questo riquadro fornisce una versione leggibile di molti dei file manifest e consente di verificare che tutte le immagini vengano caricate correttamente.

Schermate iniziali sui dispositivi mobili

Al primo avvio dell'app su un dispositivo mobile, il browser potrebbe richiedere alcuni istanti e i contenuti iniziali per iniziare il rendering. Invece di mostrare un schermata bianca che potrebbe far pensare all'utente che l'app non funziona, il browser mostra una schermata iniziale fino al primo colore.

Chrome crea automaticamente la schermata iniziale da name, background_color e icons specificati nel file manifest. Per creare un'immagine uniforme la transizione dalla schermata iniziale all'app, background_color dello stesso colore della pagina di caricamento.

Chrome sceglie l'icona che più si avvicina alla risoluzione del dispositivo per nelle schermate iniziali. Nella maggior parte dei casi è sufficiente fornire icone da 192 px e 512 px. ma puoi fornire altre icone per una corrispondenza migliore.

Per approfondire

Per informazioni su altre proprietà che puoi aggiungere al file manifest dell'app web, consulta la documentazione relativa ai file manifest dell'app web MDN.