網頁應用程式資訊清單

網頁應用程式資訊清單是您建立的檔案，用於告知瀏覽器如何在作業系統中以應用程式形式顯示網頁內容。資訊清單可包含基本資訊，例如應用程式的名稱、圖示和主題顏色；進階偏好設定，例如所需的螢幕方向和應用程式快捷方式；以及目錄中繼資料，例如螢幕截圖。

每個 PWA 應包含每個應用程式的單一資訊清單，通常會託管在根目錄中，並連結至可安裝 PWA 的所有 HTML 頁面。其正式副檔名為 .webmanifest，因此您可以將資訊清單命名為 app.webmanifest。

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

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

app.webmanifest:

{
   "name": "My First Application"
}

不過，建立檔案還不夠，瀏覽器也必須知道檔案的存在位置。

連結至資訊清單

如要讓瀏覽器瞭解您的網頁應用程式資訊清單，您必須使用 <link> HTML 元素，並在所有 PWA 的 HTML 網頁中將 rel 屬性設為 manifest，以便連結至 PWA。這與將 CSS 樣式表連結至文件的做法類似。

index.html:

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

對資訊清單進行偵錯

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

適用於 Chromium 瀏覽器

在開發人員工具中

  1. 在左側窗格中的「Application」下方，選取「Manifest」。
  2. 檢查瀏覽器剖析的資訊清單欄位。

Firefox

  1. 開啟檢查器。
  2. 前往「應用程式」分頁。
  3. 選取左側面板中的「Manifest」選項。
  4. 檢查瀏覽器剖析的資訊清單欄位。

設計 PWA 體驗

您的 PWA 已連結至其資訊清單，現在是時候填寫其他欄位，為使用者定義體驗。

基本欄位

第一組欄位代表 PWA 的核心資訊。這些屬性可用於建構已安裝 PWA 的圖示和視窗，並決定啟動方式。這 3 個子類型如下：

name
PWA 的完整名稱。這個圖示會與操作系統的主畫面、啟動器、Dock 或選單中的圖示一併顯示。
short_name
選用，PWA 的簡寫名稱，用於顯示 name 欄位完整值時空間不足的情況。請將長度控制在 12 個半形字元以內，盡量減少遭到截斷的可能性。
icons
含有 src、type、sizes 和選用 purpose 欄位的圖示物件陣列，說明應使用哪些圖片代表 PWA。
start_url
使用者從已安裝的圖示啟動 PWA 時應載入的網址。建議您使用絕對路徑，因此如果 PWA 首頁是網站的根目錄，您可以將此路徑設為「/」，在應用程式啟動時開啟該路徑。如果您未提供啟動網址，瀏覽器可以使用安裝 PWA 的網址做為啟動網址。可以是深層連結，例如產品詳細資料，而非主畫面。
display
fullscreen、standalone、minimal-ui 或 browser 其中一個，說明作業系統應如何繪製 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 是一款免費的線上工具，可用來測試及建立可遮罩的圖示版本。

如果圖示用於一般和可遮蔽的用途，您可以將 purpose 欄位設為 "any maskable"。詳情請參閱 MDN Web App 資訊清單說明文件。

接下來要加入的欄位組合可改善使用者體驗，但並非安裝可用性所需。

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

下圖顯示安裝 PWA 時，theme_color 欄位如何用於電腦裝置的標題列。

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

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

立即試用

啟動畫面

在某些裝置上，系統會在載入 PWA 時算繪靜態圖片，以便立即向使用者提供意見回饋。

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

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

Android 啟動畫面上的 PWA，會從資訊清單取得不同值。

另一方面，iOS 和 iPadOS 上的 Safari 不會使用 webapp 資訊清單產生啟動畫面。而是使用從專屬 <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 適合哪些年齡層使用。

您現在就能使用這些宣傳欄位。舉例來說，在 Android 上，如果 PWA 可安裝，且您至少為 description 和 screenshots 欄位提供值，安裝對話方塊體驗就會從簡單的「新增至主畫面」資訊列，轉變為類似應用程式商店的更豐富安裝對話方塊。

在 Android 上，如果您為宣傳欄位提供值，就能獲得更優質的安裝 UI，如下一則影片所示

查看以下宣傳欄位的實際運作方式：

功能欄位

最後，有許多欄位與 PWA 可在支援的瀏覽器中使用的不同功能有關，例如「功能」一章中介紹的 shortcuts、share_target 和 display_override 欄位。還有 related_apps 和 prefer_related_apps 等欄位 (詳情請參閱「偵測」一節)，可將 PWA 連結至已安裝的應用程式，這些應用程式通常來自應用程式商店。

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

資源