網頁應用程式資訊清單是由您建立的檔案,告知瀏覽器您希望網路內容在作業系統中如何顯示為應用程式。資訊清單可包含基本資訊 (例如應用程式名稱、圖示和主題顏色)、進階偏好設定 (例如所需的螢幕方向和應用程式捷徑),以及目錄中繼資料 (例如螢幕截圖)。
每個 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 瀏覽器
在開發人員工具中
- 在左側窗格的「應用程式」下方,選取「資訊清單」。
- 根據瀏覽器剖析的資訊檢查資訊清單欄位。
適用於 Firefox
- 開啟檢查器。
- 前往「Application」分頁。
- 選取左側面板中的「資訊清單」選項。
- 根據瀏覽器剖析的資訊檢查資訊清單欄位。
設計 PWA 體驗
您的 PWA 現已連結至資訊清單後,接下來就應填寫其餘欄位,定義使用者體驗。
基本欄位
第一組欄位代表 PWA 的核心資訊。它們會用來建構已安裝的 PWA 圖示和視窗,並判斷應用程式的啟動方式。這些因素包括:
name
- PWA 的全名。縮圖和圖示會連同圖示一起顯示在作業系統的主畫面、啟動器、座架或選單中。
short_name
- 選用 (選用) 縮短 PWA 的名稱,在空間不足以顯示
name
欄位的完整值時使用。將長度控制在 12 個半形字元以內,盡量避免發生截斷的情形。 icons
- 圖示物件陣列,包含
src
、type
、sizes
和選用的purpose
欄位,用於描述應代表 PWA 的圖片。 start_url
- 當使用者透過已安裝的圖示啟動 PWA 時,PWA 應載入的網址。建議您使用絕對路徑,因此如果 PWA 的首頁是網站的根目錄,則可將其設為「/」,以便在應用程式啟動時開啟網頁。如果未提供起始網址,瀏覽器可以直接使用 PWA 從安裝到的網址。可以是深層連結,例如產品詳細資料,而非主畫面。
display
fullscreen
、standalone
、minimal-ui
或browser
的其中一個,說明 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%。(請參閱下圖)。如果裝置支援可遮蓋的圖示,就會視需要遮蓋圖示。
以下是可遮蓋的圖示範例,該圖示以多種常用形狀呈現:
在下圖中,如果您使用左側的圖示做為可遮蓋的圖示,則套用該形狀遮罩後,產生的結果會不佳。
加入更多邊框間距之後,這張圖片或許就能派上用場。
可遮蓋的圖示至少應為 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
欄位在電腦裝置上的標題列。
定義資訊清單中 (例如在 theme_color
和 background_color
中) 的顏色時,應使用 CSS 命名顏色 (例如 salmon
或 orange
、#FF5500
等 RGB 顏色),或是不具透明度 (例如 rgb()
或 hsl()
) 的顏色函式。如需更多資訊,請參閱「應用程式設計章節」。
立即體驗
啟動畫面
在某些裝置上,PWA 載入時會顯示靜態圖片,以便立即向使用者提供意見回饋。
Android 會使用 theme_color
、background_color
和 icon
值產生啟動畫面。
在 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 適合哪些年齡層。
目前這些宣傳欄位的實際運作情形。舉例來說,在 Android 上,如果您的 PWA 可安裝,且至少為 description
和 screenshots
欄位提供值,安裝對話方塊體驗會從簡單的「新增至主畫面」資訊列,轉換為更豐富的安裝對話方塊,類似於應用程式商店中的安裝對話方塊。
在 Android 上,只要提供促銷活動欄位的值,就能取得更棒的安裝 UI,如下一部影片所示
下列宣傳欄位的實際運作情形:
功能欄位
最後,針對 PWA 可在支援的瀏覽器中使用的各項功能,還有一些與 PWA 功能相關的欄位,例如「功能」章節所涵蓋的 shortcuts
、share_target
、display_overrides
欄位。此外,還有 related_apps
和 prefer_related_apps
這類欄位 (詳情請參閱偵測章節),可以將 PWA 連結至已安裝的應用程式 (通常是從應用程式商店)。
瀏覽器未來可能會出現許多新欄位,而瀏覽器為漸進式網頁應用程式提供更多功能。