網頁應用程式資訊清單

網頁應用程式資訊清單是您建立的檔案，可讓瀏覽器瞭解您希望網路內容在作業系統中以應用程式的方式呈現。資訊清單可以包含應用程式名稱、圖示和主題顏色等基本資訊；進階偏好設定，例如所需的螢幕方向和應用程式捷徑和目錄中繼資料，例如螢幕截圖

每個 PWA 都應該為每個應用程式加入一個資訊清單，通常由根資料夾代管，且會連結到所有能夠安裝 PWA 的 HTML 頁面。該擴充功能的官方擴充功能為 .webmanifest，因此您可以為資訊清單命名，例如 app.webmanifest。

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

如要建立網頁應用程式資訊清單，請先使用 JSON 物件建立文字檔案，當中須包含至少一個含有字串值的 name 欄位：

app.webmanifest:

{
   "name": "My First Application"
}

然而，建立檔案是不夠的，瀏覽器也必須知道檔案存在。

連結至資訊清單

如要讓瀏覽器偵測您的網頁應用程式資訊清單，您需要使用 <link> HTML 元素，並將 rel 屬性 (在所有 PWA 的 HTML 網頁上) 都設為 manifest，以連結至 PWA。這類似於將 CSS 樣式表連結至文件的方式。

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">
敬上

對資訊清單偵錯

為確保資訊清單設定正確，您可以在所有採用 Chromium 的瀏覽器中使用 Firefox 和開發人員工具中的檢查器。

適用於 Chromium 瀏覽器

在開發人員工具中

  1. 在左側窗格中的「應用程式」下方，選取「資訊清單」。
  2. 根據瀏覽器剖析的資訊清單欄位檢查各個欄位。

Firefox 適用

  1. 開啟檢查器。
  2. 前往「應用程式」分頁。
  3. 選取左側面板中的「資訊清單」選項。
  4. 根據瀏覽器剖析的資訊清單欄位檢查各個欄位。
，瞭解如何調查及移除這項存取權。

設計 PWA 體驗

將 PWA 連結至資訊清單後，您現在可以填寫其餘欄位，為使用者定義體驗。

基本欄位

第一組欄位代表 PWA 的核心資訊。可用於建立已安裝 PWA 的圖示和視窗，並決定其啟動方式。這些因素包括：

name
PWA 的全名。在作業系統的主畫面、啟動器、座架或選單中，圖示會與圖示一同顯示。
short_name
如果空間不足以顯示 name 欄位的完整值，就會使用較短的 PWA 名稱。長度不超過 12 個半形字元，盡可能降低遭到截斷的可能性。
icons
圖示物件陣列，其中包含 src、type、sizes 和選用的 purpose 欄位，說明哪些圖片應代表 PWA。
start_url
使用者透過已安裝圖示啟動 PWA 時，系統應載入的網址。建議您使用絕對路徑，因此，如果 PWA 首頁為網站的根目錄，請將此設為「/」。如果您未提供起始網址，瀏覽器便可使用從 PWA 安裝的網址開始著手。可以是深層連結，例如產品詳細資料，而非主畫面。
display
fullscreen、standalone、minimal-ui 或 browser 的其中一個，用於說明 OS 應如何繪製 PWA 視窗。如要進一步瞭解不同的顯示模式，請參閱應用程式設計章節。大部分用途都會實作 standalone。
id
這個字串專門用於識別此 PWA，與可能代管於相同來源的其他 PWA。如未設定，則會使用 start_url 做為備用值。請注意，如果日後變更 start_url (例如變更查詢字串值)，瀏覽器將偵測是否已安裝 PWA。
，瞭解如何調查及移除這項存取權。
，瞭解如何調查及移除這項存取權。

圖示

PWA 的圖示代表所有使用者的視覺形象因此你必須定義至少一個裝置。由於 icons 屬性是圖示物件的集合，因此您可以定義多個不同格式的圖示，為使用者提供最佳圖示體驗。每個瀏覽器都會根據需求和所安裝的作業系統，挑選一或多個圖示，圖示的規格越接近所需的規格。

如果只需選擇一種圖示大小，尺寸應為 512 x 512 像素。不過，建議您提供更多尺寸，包括 192 x 192、384 x 384 和 1024 x 1024 像素大小的圖片。

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]
敬上

如未提供圖示，或圖示未達建議大小，在部分平台上就無法通過安裝條件。在其他平台上，系統會自動產生圖示。例如從 PWA 螢幕截圖中，或是使用一般圖示。

可遮蓋的圖示

部分作業系統 (例如 Android) 會根據不同的大小和形狀調整圖示。舉例來說，在 Android 12 上，不同的製造商或設定可以將圖示的形狀從圓形變更為正方形，並轉換為圓角方角。如要支援這些類型的自動調整圖示，您可以使用 purpose 欄位提供可遮蓋的圖示。

為此，請提供含有主要圖示的正方形圖片檔，且該圖片位於圖示中心，並以圖示寬度的 40% 為中心。(請參閱下圖)。如果裝置支援可遮蓋的圖示，就會視需要遮蓋圖示。

正方形圖示中，有 40% 中心半徑所標示的安全區域

以下是可遮蓋的圖示範例，這些圖示透過多種常用形狀呈現：

在下圖中，如果將左側的圖示用做可遮蓋的圖示，套用形狀遮罩後，裝置所呈現的結果會比較差。

不適用於可遮蓋圖示的圖示。

我們可以為這張圖片加上更多邊框間距。

邊框間距較多的圖示適用於遮罩。

可遮蓋圖示的大小至少應為 512 x 512。你可以將已建立的影片加入「icons」集合，為支援的裝置提升使用體驗：

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

在多數情況下，如果可遮蓋的圖示未能正確顯示，您可以新增更多邊框間距，藉此改善圖示。Maskable.app 是一項免費線上工具，可用來測試及建立可遮蓋的圖示版本。

下一組要加入的欄位將是改善使用者體驗的欄位，即使這些欄位在安裝時並非必要。

theme_color
應用程式的預設顏色，有時會影響作業系統顯示網站的方式 (例如電腦上的視窗和標題列顏色，或行動裝置上的狀態列顏色)。HTML theme-color <meta> 元素可覆寫這個顏色。
background_color
在載入其樣式表之前，顯示在應用程式背景的預留位置顏色。iOS 和 iPadOS 上的 Safari 和大部分電腦版瀏覽器目前會忽略這個欄位。
scope
變更 PWA 的導覽範圍，方便你定義已安裝應用程式視窗中的內容，以及不會顯示的內容。舉例來說，如果您要連結至範圍外的網頁，該頁面會在應用程式內瀏覽器中顯示，而不是 PWA 視窗。不過，這不會變更 Service Worker 的範圍。

下一張圖片說明在安裝 PWA 時，電腦標題列如何使用 theme_color 欄位。

在電腦上安裝相同 PWA，但主題顏色不同。

在資訊清單中定義顏色時 (例如在 theme_color 和 background_color 內定義顏色)，應使用 CSS 命名顏色 (例如 salmon 或 orange)、#FF5500 等 RGB 顏色，或是不透明的色彩函式 (例如 rgb() 或 hsl())。詳情請參閱應用程式設計章節。

立即試用

啟動畫面

在某些裝置上，系統會在 PWA 載入時轉譯靜態圖片，為使用者提供即時回應。

Android 會使用 theme_color、background_color 和 icon 值產生啟動畫面。

在 Android 上安裝 PWA 時，裝置會產生啟動畫面，當中包含從資訊清單擷取的資訊，如下圖所示。

Android 啟動畫面的 PWA 採用的資訊清單值不同。

另一方面，iOS 和 iPadOS 版 Safari 不會使用網頁應用程式資訊清單產生啟動畫面。而是使用從專屬 <link> 元素連結的圖片，方法與處理圖示的方式類似。詳情請參閱強化章節。

延伸欄位

下一組欄位會提供 PWA 的額外資訊。這些都是選擇性的。

lang
指定資訊清單值主要語言的語言標記，例如 en 為英文、pt-BR 代表巴西葡萄牙文，in 代表北印度文。
dir
顯示支援方向的資訊清單欄位 (例如 name、short_name 和 description) 的方向。有效值為 auto、ltr (從左到右) 和 rtl (從右到左)。
orientation
安裝後的應用程式所需螢幕方向。遊戲可能會將其設為要求僅限橫向的螢幕方向。系統接受多個值，但明確包括通常都是 portrait 或 landscape。
，瞭解如何調查及移除這項存取權。

促銷欄位

第四個欄位可讓您提供 PWA 的宣傳資訊 (例如在安裝流程、產品資訊和搜尋結果中)。

description
說明 PWA 的功能。
screenshots
包含 src、type 和 sizes (類似 icons 物件) 的螢幕截圖物件陣列，用於展示 PWA。不受大小限制。
categories
PWA 所屬的類別陣列，要用做清單提示，也可以選擇從已知類別清單中選擇。這些值通常為小寫。
iarc_rating_id
PWA 的國際年齡分級聯盟認證號碼 (如果有的話)。這項功能是用來判斷 PWA 適合哪些年齡層。
，瞭解如何調查及移除這項存取權。

您立即就能查看這些促銷欄位的實際運作情形。舉例來說，如果您的 PWA 可安裝，且您至少提供 description 和 screenshots 欄位的值，安裝對話方塊體驗就會透過簡單的「新增至主畫面」轉換。資訊列，提供功能更豐富的安裝對話方塊，類似於應用程式商店中的對話方塊。

在 Android 裝置上，只要為促銷欄位提供值，就能打造更優質的安裝使用者介面，詳情請見下部影片

查看這些促銷欄位的實際運作情形：

能力欄位

最後，有些欄位與 PWA 在支援的瀏覽器中使用的功能有關，例如「功能」章節所介紹的 shortcuts、share_target、display_overrides 欄位。此外，您也可使用 related_apps 和 prefer_related_apps 等欄位 (詳情請參閱偵測章節)，將 PWA 連結至已安裝的應用程式，而且通常是來自應用程式商店。

隨著瀏覽器為漸進式網頁應用程式提供更多功能，未來可能會出現許多新欄位。

資源