網頁應用程式資訊清單

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

每個 PWA 都應為每個應用程式包含一份資訊清單 (通常位於根資料夾中),並連結至可安裝 PWA 的所有 HTML 頁面。其官方擴充功能為 .webmanifest,因此您可以針對資訊清單命名,例如 app.webmanifest

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

如要建立網頁應用程式資訊清單,請先使用至少含有 name 欄位且字串值的 JSON 物件建立文字檔案:

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">

對資訊清單進行偵錯

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

適用於 Chromium 瀏覽器

在開發人員工具中

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

適用於 Firefox

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

設計 PWA 體驗

您的 PWA 現已連結至資訊清單後,接下來就應填寫其餘欄位,定義使用者體驗。

基本欄位

第一組欄位代表 PWA 的核心資訊。它們會用來建構已安裝的 PWA 圖示和視窗,並判斷應用程式的啟動方式。這些因素包括:

name
PWA 的全名。縮圖和圖示會連同圖示一起顯示在作業系統的主畫面、啟動器、座架或選單中。
short_name
選用 (選用) 縮短 PWA 的名稱,在空間不足以顯示 name 欄位的完整值時使用。將長度控制在 12 個半形字元以內,盡量避免發生截斷的情形。
icons
圖示物件陣列,包含 srctypesizes 和選用的 purpose 欄位,用於描述應代表 PWA 的圖片。
start_url
當使用者透過已安裝的圖示啟動 PWA 時,PWA 應載入的網址。建議您使用絕對路徑,因此如果 PWA 的首頁是網站的根目錄,則可將其設為「/」,以便在應用程式啟動時開啟網頁。如果未提供起始網址,瀏覽器可以直接使用 PWA 從安裝到的網址。可以是深層連結,例如產品詳細資料,而非主畫面。
display
fullscreenstandaloneminimal-uibrowser 的其中一個,說明 OS 應如何繪製 PWA 視窗。如要進一步瞭解不同的顯示模式,請參閱「應用程式設計」章節。「大部分」用途都實作 standalone
id
此字串可用於識別此 PWA,以及可能由同一來源代管的其他 PWA。如未設定,系統會使用 start_url 做為備用值。請注意,日後變更 start_url (例如變更查詢字串值時) 可能會移除瀏覽器偵測 PWA 是否已安裝 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#FF5500 等 RGB 顏色),或是不具透明度 (例如 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 上,只要提供促銷活動欄位的值,就能取得更棒的安裝 UI,如下一部影片所示

下列宣傳欄位的實際運作情形:

功能欄位

最後,針對 PWA 可在支援的瀏覽器中使用的各項功能,還有一些與 PWA 功能相關的欄位,例如「功能」章節所涵蓋的 shortcutsshare_targetdisplay_overrides 欄位。此外,還有 related_appsprefer_related_apps 這類欄位 (詳情請參閱偵測章節),可以將 PWA 連結至已安裝的應用程式 (通常是從應用程式商店)。

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

資源