網頁應用程式資訊清單

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

每個 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
如果空間不足以顯示 name 欄位的完整值,就會使用較短的 PWA 名稱。請將長度控制在 12 個半形字元以內,盡量減少遭到截斷的可能性。
icons
圖示物件陣列,其中包含 srctypesizes 和選用的 purpose 欄位,說明哪些圖片應代表 PWA。
start_url
使用者從已安裝的圖示啟動 PWA 時應載入的網址。建議您使用絕對路徑,因此如果 PWA 首頁是網站的根目錄,您可以將此路徑設為「/」,在應用程式啟動時開啟該路徑。如果您未提供啟動網址,瀏覽器可以使用安裝 PWA 的網址做為啟動網址。可以是深層連結,例如產品詳細資料,而非主畫面。
display
fullscreenstandaloneminimal-uibrowser 的其中一個,用於說明 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 視窗中顯示。不過,這不會變更服務工作者的範圍。

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

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

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

立即試用

啟動畫面

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

Android 會使用 theme_colorbackground_coloricon 值產生啟動畫面。

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

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

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

擴充欄位

接下來這組欄位會提供 PWA 的其他資訊。這些都是選用項目。

lang
語言代碼,指定資訊清單值的主要語言,例如 en 代表英文、pt-BR 代表巴西葡萄牙文,或 in 代表北印度文。
dir
顯示支援方向的資訊清單欄位 (例如 nameshort_namedescription) 的方向。有效值為 autoltr (從左到右) 和 rtl (從右到左)。
orientation
安裝後的應用程式所需螢幕方向。遊戲可能會將這項屬性設為要求僅限橫向模式。系統接受多個值,但明確包括通常都是 portraitlandscape

宣傳欄位

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

description
PWA 的功能說明。
screenshots
螢幕截圖物件陣列,其中包含 srctypesizes (類似 icons 物件),用於展示 PWA。沒有大小限制。
categories
PWA 所屬的類別陣列,要用做清單提示,也可以選擇從已知類別清單中選擇。這些值通常為小寫。
iarc_rating_id
如果有,請提供 PWA 的國際年齡分級聯盟認證代碼。這項功能是用來判斷 PWA 適合哪些年齡層。

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

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

查看以下宣傳欄位的實際運作情形:

功能欄位

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

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

資源