新增網頁應用程式資訊清單

François Beaufort
François Beaufort
GitHub
Pete LePage
Thomas Steiner
Alexey Rodionov
Alexey Rodionov
X GitHub LinkedIn

瀏覽器支援

  • 39
  • 79
  • x
  • x

資料來源

網頁應用程式資訊清單是一種 JSON 檔案，用於告知瀏覽器漸進式網頁應用程式 (PWA) 安裝在使用者電腦或行動裝置上時應呈現的行為。一般的資訊清單檔案至少包含：

  • 應用程式名稱
  • 應用程式應使用的圖示
  • 應用程式啟動時要開啟的網址

建立資訊清單檔案

資訊清單檔案中可以有任何名稱，但名稱通常為 manifest.json，且會從根目錄 (您網站的頂層目錄) 提供。規格建議擴充功能應為 .webmanifest，但建議您使用 JSON 檔案，讓資訊清單更清楚易讀。

一般資訊清單如下所示：

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

主要資訊清單屬性

short_name和name

您必須在資訊清單中至少提供一項 short_name 或 name。如果同時提供兩者，系統會在應用程式安裝時使用 name，而使用者的主畫面、啟動器或其他空間有限的位置會使用 short_name。

icons

使用者安裝 PWA 時，您可以定義一組圖示，供瀏覽器在主畫面、應用程式啟動器、工作切換器、啟動畫面和其他位置使用。

icons 屬性是圖片物件的陣列。每個物件都必須包含 src、sizes 屬性和圖片的 type。如要使用可遮蓋的圖示 (在 Android 上有時稱為自動調整圖示)，請在 icon 屬性中加入 "purpose": "any maskable"。

如果是 Chromium，您必須提供至少 192 x 192 像素的圖示和 512 x 512 像素的圖示。如果系統只提供這兩種圖示大小，Chrome 會自動依據裝置調整圖示大小。如果您想自行調整圖示大小，並配合像素完美呈現，請提供以 48dp 為單位遞增的圖示。

id

id 屬性可讓您明確定義應用程式使用的 ID。在資訊清單中新增 id 屬性，即可移除 start_url 或資訊清單位置的依附元件，且可在日後更新。詳情請參閱「使用網頁應用程式資訊清單 ID 屬性專屬識別 PWA」一文。

start_url

start_url 是必要屬性。這會讓瀏覽器知道應用程式啟動時應該啟動，並防止應用程式在使用者將應用程式新增至主畫面時從哪個網頁啟動。

start_url 應將使用者直接帶往應用程式，而不是產品到達網頁。思考使用者開啟您的應用程式後，您希望採取什麼行動，並放在該處。

background_color

應用程式首次在行動裝置上啟動時，啟動畫面會使用 background_color 屬性。

display

您可以自訂應用程式啟動時所顯示的瀏覽器 UI。舉例來說，您可以隱藏網址列和瀏覽器使用者介面元素，您甚至可以製作以全螢幕模式啟動遊戲。display 屬性可使用下列其中一個值：

屬性 行為
fullscreen 在不使用任何瀏覽器 UI 的情況下開啟網頁應用程式，並佔滿所有可用的顯示區域。
standalone 開啟網頁應用程式的外觀和風格，如同獨立應用程式。應用程式會在獨立視窗中執行，與瀏覽器分開，並隱藏標準瀏覽器 UI 元素 (例如網址列)。
採用獨立螢幕的 PWA 視窗範例。
獨立 UI。
minimal-ui 這個模式與 standalone 類似，但為使用者提供用來控制導覽的 UI 元素最低限度，例如返回和重新載入按鈕。
採用極簡 UI 顯示的 PWA 視窗範例。
最小的使用者介面。
browser 標準的瀏覽器體驗。

display_override

如要選擇網頁應用程式顯示方式，請在資訊清單中設定 display 模式，如先前所述。瀏覽器不必支援所有顯示模式，但瀏覽器「必須」支援規格定義的備用鏈結 ("fullscreen" → "standalone" → "minimal-ui" → "browser")。如果瀏覽器不支援特定模式，就會切換回鏈結中的下一個顯示模式。在極少數的情況下，這些備用項可能會造成問題。舉例來說，如果系統不支援 "minimal-ui"，開發人員就無法在未強制返回 "browser" 顯示模式的情況下要求 "minimal-ui"。目前的行為也使無法透過回溯相容的方式導入新的顯示模式，因為這些模式沒有在備用鏈中具有位置。

您可以使用 display_override 屬性自行設定備用序列，瀏覽器會在 display 屬性「之前」考量這項屬性。其值是按照所列順序考慮的一系列字串，並套用第一個支援的顯示模式。如果沒有任何支援，瀏覽器會改回使用評估 display 欄位。如果沒有 display 欄位，瀏覽器會忽略 display_override。

以下為如何使用 display_override 的範例。"window-control-overlay" 的詳細資料不在本頁說明的範圍內。

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

載入這個應用程式時，瀏覽器會先嘗試使用 "window-control-overlay"。如果不適用，會改回使用 "minimal-ui"，再從 display 屬性轉換為 "standalone"。如果這些方法都不適用，瀏覽器就會回到標準備用廣告鏈。

scope

應用程式的 scope 是瀏覽器考量到應用程式的一組網址。scope 會控制網址結構，其中包含應用程式的所有進入和離開點，瀏覽器則會使用該結構來判斷使用者是否已離開應用程式。

scope 的其他注意事項：

  • 如果您未在資訊清單中加入 scope，則預設的 scope 即為起始網址，但會移除檔案名稱、查詢和片段。
  • scope 屬性可以是相對路徑 (../)，也可以是任何較高層級的路徑 (/)，以便提高網頁應用程式的導覽涵蓋範圍。
  • start_url 必須位於範圍內。
  • start_url 是相對於 scope 屬性中定義的路徑。
  • 以 / 開頭的 start_url 一律是來源的根。

theme_color

theme_color 會設定工具列的顏色，並且可反映在工作切換器的應用程式預覽畫面中。theme_color 應與文件標題中指定的 meta 主題顏色相符。

採用自訂 theme_color 的 PWA 視窗範例。
含有自訂 theme_color 的 PWA 視窗範例。

媒體查詢次數：theme_color

瀏覽器支援

  • 93
  • 93
  • 106
  • 15

資料來源

您可以使用 meta 主題顏色元素的 media 屬性，調整媒體查詢中的 theme_color。例如，您可以為淺色模式和深色模式定義另一個顏色。不過，您無法在資訊清單中定義這些偏好設定。詳情請參閱 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

shortcuts 屬性是應用程式捷徑物件的陣列，可用來快速存取應用程式內的重要工作。每個成員都是包含至少 name 和 url 的字典。

description

description 屬性說明瞭應用程式的用途。

在 Chrome 中，說明長度上限為 300 個半形字元 (所有平台上)。 如果說明長度超過限制，瀏覽器會以刪節號字元截斷說明。在 Android 上，說明也必須使用最多七行文字。

screenshots

screenshots 屬性是圖片物件陣列，代表用於常見用途的應用程式。每個物件都必須包含 src、sizes 屬性和圖片的 type。form_factor 為選用屬性，您可以將此值設為 "wide" (適用於僅限寬螢幕的螢幕截圖)，也可以設為 "narrow" (僅適用於狹窄的螢幕截圖)。

在 Chrome 中，圖片必須符合下列條件：

  • 寬度和高度不得小於 320 像素，且不得超過 3840 像素。
  • 尺寸上限不得大於最小尺寸長度的 2.3 倍。
  • 所有符合適當板型規格的螢幕截圖，顯示比例都必須相同。
    • 從 Chrome 109 開始，只有 form_factor 設為 "wide" 的螢幕截圖會顯示在電腦中。
  • 從 Chrome 109 開始，Android 會忽略 form_factor 設為 "wide" 的螢幕截圖。為確保回溯相容性，不含 form_factor 的螢幕截圖。

電腦版 Chrome 會顯示至少一、最多八張符合這些條件的螢幕截圖。因此將忽略其他螢幕截圖。

Android 版 Chrome 會顯示至少一、最多五個符合這些條件的螢幕截圖。因此將忽略其他螢幕截圖。

更豐富的電腦和行動裝置安裝 UI 螢幕截圖。
更豐富的電腦和行動裝置介面安裝使用者介面。

建立資訊清單後，請在漸進式網頁應用程式的所有頁面中新增 <link> 標記，例如：

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

測試您的資訊清單

如要驗證資訊清單設定是否正確，請使用 Chrome 開發人員工具「Application」面板中的「Manifest」窗格。

Chrome 開發人員工具中的應用程式面板，已選取資訊清單分頁。
在開發人員工具中測試資訊清單。

這個窗格提供許多資訊清單屬性的人類可讀版本，方便您驗證所有圖片是否能正確載入。

行動裝置上的啟動畫面

應用程式首次在行動裝置上啟動時，瀏覽器可能需要一些時間才會啟動，以及開始轉譯初始內容。瀏覽器不會在第一次繪製之前顯示啟動畫面，而不是顯示可能會讓使用者認為應用程式無法正常運作的白色畫面。

Chrome 會自動從資訊清單中指定的 name、background_color 和 icons 建立啟動畫面。如要建立從啟動畫面順暢轉換到應用程式，請將 background_color 的顏色設為與載入頁面相同的顏色。

Chrome 會選擇最接近啟動畫面裝置解析度的圖示。在大多數情況下，提供 192px 和 512px 的圖示就足以滿足大多數情況，但您可以提供更多圖示，讓圖片更貼近您的需求。

其他資訊

如要瞭解可加入網頁應用程式資訊清單的其他屬性，請參閱 MDN 網頁應用程式資訊清單說明文件。