本頁面由 Cloud Translation API 翻譯而成。

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

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

瀏覽器支援

資料來源

網頁應用程式資訊清單是 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。使用條件可遮蓋的圖示，有時也稱為自動調整圖示，請將 "purpose": "any maskable" 新增至 icon 屬性。

針對 Chromium，您必須提供至少 192 x 192 像素的圖示和 512 x 512 像素的圖示。如果只提供這兩種圖示大小，Chrome 自動調整圖示以配合裝置尺寸。如果想，並依像素風格調整這些圖示，同時提供遞增的圖示最低為 48 dp

`id`

id 屬性可讓您明確定義應用程式。在資訊清單中新增 id 屬性，會移除 start_url 或資訊清單的位置，而且能夠更新日後若需更多資訊，請參閲使用網頁應用程式資訊清單 ID 屬性明確識別 PWA。

`start_url`

start_url 是必要屬性。可讓瀏覽器瞭解應用程式應在啟動後啟動，並防止應用程式在啟動時啟動也就是使用者將應用程式加入主畫面時所在的網頁。

您的 start_url 應將使用者直接導向應用程式，而非產品到達網頁想想使用者會希望採取什麼行動開啟應用程式並置入

`background_color`

出現 background_color 屬性時，啟動畫面會使用這是我們第一次在行動裝置上推出應用程式

`display`

您可以自訂應用程式啟動時要顯示的瀏覽器使用者介面。適用對象例如，您可以隱藏網址列和瀏覽器的使用者介面元素。遊戲甚至可以啟動全螢幕display 屬性會採用以下其中一個值：下列值：

屬性	行為
`fullscreen`	不需任何瀏覽器 UI 就能開啟網頁應用程式，並佔據所有可用的顯示區域。
`standalone`	開啟網頁應用程式，外觀與風格類似獨立的應用程式。應用程式執行在瀏覽器視窗中獨立於瀏覽器視窗中，並隱藏標準圖片瀏覽器的 UI 元素，例如網址列獨立 UI 。
`minimal-ui`	這個模式與 `standalone` 類似，但會提供僅使用少量 UI 元素控制導覽功能例如返回和重新載入按鈕最精簡的 UI。
`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主題顏色。

採用自訂主題_color 的 PWA 視窗範例。 — 包含自訂 `theme_color` 的 PWA 視窗範例。

媒體查詢中的`theme_color`

瀏覽器支援

資料來源

您可以使用 media 屬性，在媒體查詢中調整 theme_color meta主題顏色元素。舉例來說，您可以為淺色模式定義一個顏色另一個則是深色模式不過，您無法定義資訊清單中的偏好設定若需更多資訊，請參閲 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 中，form_factor 設為 "wide" 的螢幕截圖如下在 Android 上會忽略但下列使用者仍會顯示沒有「form_factor」的螢幕截圖：具備回溯相容性

Chrome 電腦版會顯示至少一張及最多八張符合這些條件。其餘將忽略。

Android 版 Chrome 會顯示至少一張和最多五張符合的螢幕擷取畫面這些條件。其餘將忽略。

在電腦和行動裝置上提供功能豐富的安裝使用者介面螢幕截圖。 — 在電腦和行動裝置上提供更豐富的安裝使用者介面。

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

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

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

敬上

系統會「不會」提出資訊清單要求就算同一個網域上也是如此。如果資訊清單憑證，必須包含 crossorigin="use-credentials" 。

測試資訊清單

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

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

這個窗格提供清楚易懂的許多資訊清單版本並確認所有圖片都能正常載入正確做法。

行動裝置上的啟動畫面

應用程式首次在行動裝置上啟動時，瀏覽器可能需要一點時間開始轉譯內容。與其顯示這可能讓使用者誤以為應用程式無法運作持續顯示啟動畫面，直到第一次繪製為止。

Chrome 會自動從 name 建立啟動畫面，在資訊清單中指定的background_color和icons。營造流暢的氛圍因此，請務必background_color 和載入網頁的顏色

Chrome 會選擇最符合裝置解析度的圖示啟動畫面在大多數情況下，提供 192 像素和 512 像素的圖示就已足夠但您可以提供其他圖示，讓模型更相符。

延伸閱讀

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

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

建立資訊清單檔案

主要資訊清單屬性

short_name和name

icons

id

start_url

background_color

display

display_override

scope

theme_color

媒體查詢中的theme_color

shortcuts

description

screenshots