PWA Web App Manifest 配置 定義 JSON 屬性優化安裝提示與離線圖示顯示

什麼是 Web App Manifest？

Web App Manifest 是一個以 JSON 格式編寫的配置檔案，它是瀏覽器識別網站為 Progressive Web App (PWA) 的關鍵依據。透過此檔案，開發者可以定義應用程式在用戶裝置上的呈現方式，包括 App 的名稱、圖示（Icon）、主題顏色、啟動頁面（start_url）以及顯示模式（如全螢幕或獨立視窗）。它讓 Web 應用具備了被「安裝」到主畫面（Home Screen）的能力，並提供類似原生 App 的啟動體驗與視覺一致性。

什麼是 Web App Manifest？PWA 配置核心

Web App Manifest 是一個簡單的 JSON 配置檔，它是讓瀏覽器識別您的網站為 Progressive Web App 的關鍵。透過這個配置檔，瀏覽器會知道該如何將 App 安裝在用戶的裝置上，包括 App 的名稱、圖示（Icon）以及啟動時的初始頁面路徑。

建立 manifest.json：從範例開始

在命名上雖然沒有強制規定，但小編建議使用標準的 manifest.json 或 .webmanifest 並放置在專案根目錄。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6"
}

Web App Manifest 配置：核心屬性解析

• name/short_name: 安裝後的 App 名稱 short_name 會用在顯示上有限制的地方
• icons: 主畫面或是任務切換時顯示
• start_url: App 開啟預設頁，須注意為相對路徑跟 manifest 位置相關，有填 Chrome 才會跳提示
• background_color: 在加入主畫面後，啟動時 splash screen 的背景主視覺，在還沒安裝前的網址列也會改變顏色
• display: 定義 App 開啟後的顯示方式目前有三種，各有細微差異 fullscreen、standalone、minimal-ui

short_name、name

兩個必須擇一填，若兩者都填

• short_name: 用在主畫面、啟動畫面或是其他顯示受限的地方
• name: 安裝時使用

background_color

啟動畫面的 splash screen 背景色

theme_color

網址列的顏色，注意要和 meta 中的顏色相同。

<meta name="theme-color" content="#3c553c" />

icons

當用戶安裝 PWA 的時候，我們可以預先提供一套不同解析度的 icon 給瀏覽器用在不同的位置，icons 是包含圖片物件的陣列，對 Chrome 來說, PWA 至少要提供 192x192 和 512x512 兩種解析度的 icon，剩下的情境 Chrome 會自動針對裝置做優化。

每一個圖片物件須包含以下屬性:

• src
• sizes
• type
• purpose: 選填，可填入 “any maskable”，在 Android 手機中可以發現 icon 會依照手機主題樣式變成圓形或其他形狀，所以 icon 在設計上可以特別注意。
  • https://web.dev/maskable-icon/

Photo Credit: https://web.dev/
透過開發者工具勾選 Show only the minimum safe area for maskable icons 來看現在的 Icon 是否 maskable

description

說明這個 App 的一些介紹。

screenshots

screenshots 是包含圖片物件的陣列, 就是 App 的使用說明截圖，description 和 screenshots 主要都是安裝相關訊息，所以目前只會用在 Android 上的 Chrome。

要滿足以下條件:

• 長寬介於 320px - 3840px
• 最大解析度不能超過最小的 2.3 倍
• 截圖要同樣的長寬比
• 僅支援 JPEG、PNG

display

透過這個屬性我們可以選擇 App 開啟後的介面，舉例來說我們可隱藏網址列使用全螢幕去操作，但並非所有的瀏覽器都完整支援，支援度會以下面的順序向下支援:

"fullscreen" → "standalone" → "minimal-ui" → "browser"

若想要跳過上面順序的某個階段，就需要透過 display_override 來蓋掉:

1
2
3
4

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

1. “window-control-overlay” (蓋掉)
2. “minimal-ui”
3. “standalone” (回到原來 display 設定的 standalone)
4. “minimal-ui”
5. “browser”

start_url

start_url 算是最重要的一個必填屬性，要告訴瀏覽器當 App 啟動時要顯示什麼畫面，避免 App 因為用戶是從其他頁面加入至主畫面導致啟動頁面是從其他頁面開始。start_url 就是用戶打開的第一個頁面，可以看成產品專用的到達頁面。所以也值得從用戶想要開啟 App 的原因去規劃 start_url 位置。

shortcuts

shortcuts 相對於 start_url則可以看成其他常用的子功能，以訂票系統來說就可以分為餘票查詢、時刻查詢等子功能，透過捷徑的配置就能夠讓用戶透過子選單直接開啟 App 並且使用功能，目前的支援度如下

• Android (Chrome 84)
• Windows (Chrome 85 and Edge 85)
• Chrome OS (Chrome 92)

1. 長按 App 開啟選單

Photo Credit: https://web.dev/

1. 桌面版 App 按右鍵開啟選單

Photo Credit: https://web.dev/

如果對捷徑功能有興趣，可以試玩看看底下這個 App:

https://app-shortcuts.glitch.me/

驗證您的 Web App Manifest 配置

透過開發者工具中的 Application Tab 可以輕鬆的察看是否我們的 manifest 有被正確的使用。

Photo Credit: https://web.dev/ >

Progressive Web App 啟動

要怎麼知道 Web App 是在 PWA 已經被安裝情況下被開啟的，靠 CSS 中有個 display-mode，不管透過 tab 或是安裝的情況下，去測試都可以看得出來。

• display-mode 搭配 matchMedia()
• navigator.standalone: 不支援 matchMedia() 就透過屬性直接判斷

1
2
3
4
5
6
7
8
9

function getPWADisplayMode() {
  const isStandalone = window.matchMedia("(display-mode: standalone)").matches;
  if (document.referrer.startsWith("android-app://")) {
    return "twa";
  } else if (navigator.standalone || isStandalone) {
    return "standalone";
  }
  return "browser";
}

偵測 display mode 改變

也是透過 matchMedia() 搭配 change 的事件，但還想不到什麼情境底下會發生。

1
2
3
4
5
6
7
8
9
10

window
  .matchMedia("(display-mode: standalone)")
  .addEventListener("change", (evt) => {
    let displayMode = "browser";
    if (evt.matches) {
      displayMode = "standalone";
    }
    // Log display mode change to analytics
    console.log("DISPLAY_MODE_CHANGED", displayMode);
  });

針對 display mode 改變 UI

最簡單就是透過 CSS 的 media query 條件設定:

1
2
3
4
5

@media all and (display-mode: standalone) {
  body {
    background-color: yellow;
  }
}

PWA 自動更新機制：如何更新已安裝的 App？

當想要更新 App 的名稱或是 Icon 的時候，其實也是透過修改 manifest 配置檔。

Chrome 桌面版

以下屬性改變的時候，Chrome 會自動抓取新的 manifest 配置檔, Chrome 會把新的配置暫存，等到所有視窗關閉時會進行更新安裝。當安裝完成時，除了 name, short_name, start_url, icons 以外的欄位都會更新。

哪幾個欄位會觸發更新?

• display: manifest 的配置、使用者 window/browser tab setting 同時存在會以使用者為主
• scope
• shortcuts
• theme_color

測試 manifest 更新

• about://internals/web-app

Chrome Android 版

哪幾個欄位會觸發更新?

• background_color
• display
• orientation
• scope
• shortcuts
• start_url
• theme_color
• web_share_target

如果 Chrome 無法從伺服器取得更新版的 manifest，會延長到 30 才進行更新確認。

測試 manifest 更新

• about://webapks:　點選 “Update” 按鈕

FAQ：Web App Manifest 常見問題

Q1：為什麼我的網站沒有跳出「安裝到主畫面」的提示？

A：Chrome 要求必須滿足以下條件：1. 必須有 manifest.json；2. 必須有 start_url；3. 至少有一張 144x192 以上的 icon；4. 必須註冊 Service Worker；5. 必須是 HTTPS。

Q2：start_url 應該設定在哪裡？

A：建議設定為您的產品首頁。如果不設定，預設會是使用者點擊「安裝」時的當前頁面，這可能導致以後打開 App 時不是從首頁開始。

Q3：修改了圖示後，使用者需要重新安裝嗎？

A：不需要。瀏覽器會定期檢查 manifest 檔案。一旦偵測到圖示 URL 改變，會在背景下載新圖示並在下次啟動時套用更新。

• ← 上一篇
• 下一篇 →