Web App Manifest(manifest.json)驗證工具

只需貼上manifest.json的內容,即可檢查是否滿足PWA的安裝條件。自動檢查name、start_url、display、icons等必填項以及maskable圖示的有無,並以列表形式顯示存在的問題。

Tips

  • 建議同時設定name和short_name。如果沒有short_name,主螢幕圖示下方顯示的文字會由name機械截斷而來,有時會出現不符合預期的顯示效果。
  • 如果沒有設定purpose: "maskable"的圖示,在部分Android裝置上,圖示周圍可能會被不自然地裁切,或者透出背景色。只需在現有的icons陣列中新增一條maskable用的條目即可解決。
  • icons中請至少提供一個192x192以上尺寸的圖示,如有可能,也請準備一個512x512以上尺寸的圖示。前者用於主螢幕圖示,後者用於啟動畫面(splash screen)的顯示。
  • Chrome等瀏覽器實際採用的PWA安裝條件今後可能會發生變化,因此本工具的判定結果僅供參考,建議最終還是通過Chrome DevTools的Application面板等進行確認。
  • start_url使用相對路徑(例如“/?source=pwa”)也沒有問題。如果想統計安裝來源,可以附加查詢引數,這樣在訪問分析中更容易區分通過PWA啟動的訪問。

常見問題

在主流瀏覽器的PWA安裝條件中,通常需要具備name或short_name中的一個、start_url、display(fullscreen、standalone、minimal-ui、browser中的一個),以及包含192x192以上尺寸的icons陣列。只要缺少其中任何一項,就有可能不會顯示安裝提示。

指的是設定了purpose: "maskable"的圖示。Android裝置會將主螢幕圖示裁切(遮罩)成圓形或圓角矩形等形狀顯示,如果直接對普通圖示影像做這種遮罩處理,圖案邊緣有時會被裁掉。maskable圖示通過在中央預留空白(安全區域)進行設計,無論被裁切成什麼形狀都能保持美觀顯示。

請使用寬和高之間用x分隔的格式指定,例如“192x192”。如果一個圖示檔案(例如SVG)適用於任意尺寸,也可以指定為“any”。如果想用一個條目表示多個尺寸,也可以用空格分隔並列寫出,例如“192x192 512x512”。

根據W3C規範,共定義了四種值:fullscreen(佔用整個螢幕)、standalone(隱藏瀏覽器介面、呈現應用般的外觀)、minimal-ui(顯示最小限度的瀏覽器介面)、browser(作為普通瀏覽器標籤頁開啟)。如果想要呈現PWA的外觀,通常會指定為standalone。

本工具僅對manifest.json的內容是否符合規範進行靜態檢查。實際能否安裝還與是否通過HTTPS提供服務、Service Worker是否正確註冊等其他條件有關,因此最終請務必同時通過瀏覽器的開發者工具或實機進行確認。
ツールくん

閒話 ― Web App Manifest與PWA的關係

Web App Manifest是由W3C制定的JSON格式規範,用於統一宣告將網站新增到主螢幕並像原生應用一樣安裝所需的資訊(應用名稱、圖示、啟動時的顯示模式、主題色等)。PWA(Progressive Web App)這個詞本身是2015年由Google的工程師提出的概念,而構成其核心的技術要素之一,正是這個manifest.json,以及負責離線執行的Service Worker這兩者。

如果manifest.json沒有正確配置,瀏覽器就不會將其識別為“可安裝的應用”,也就不會顯示提示新增到主螢幕的彈窗(例如Chrome的“安裝”橫幅)。尤其是icons解析度不足或display值錯誤這類問題,由於JSON本身在語法上仍然正確,很難被察覺,往往要等到實際嘗試安裝時才會發現。

maskable圖示(purpose: "maskable")是一個相對較新的規範,大約從2019年起為了支援Android的“自適應圖示”而新增。普通圖示會根據裝置被裁切成圓形、圓角矩形等形狀,如果準備的圖示影像沒有留白,圖案的一部分就可能被裁掉。maskable用的圖示需要設計時考慮安全區域(safe zone),通常會與普通的icons條目分開單獨準備。

本工具專注於對manifest.json本身進行靜態驗證,並不檢查Service Worker的註冊狀態、是否通過HTTPS提供服務等其他會影響實際能否安裝的條件。建議在生產環境中進行最終確認時,同時使用瀏覽器的開發者工具(例如Chrome DevTools的Application面板)加以核實。