網頁應用程式資訊清單是 JSON 檔案,可讓瀏覽器瞭解 漸進式網頁應用程式 (PWA) 應當安裝在使用者的電腦上 使用行動裝置一般的資訊清單檔案至少包含下列內容:
- 應用程式名稱
- 應用程式應使用的圖示
- 應用程式啟動時應開啟的網址
建立資訊清單檔案
資訊清單檔案可以包含任何名稱,但通常命名為 manifest.json
和
網域從根目錄 (網站的頂層目錄) 投放。規格
建議擴充功能應為 .webmanifest
,但建議使用 JSON
檔案,讓資訊清單更清晰可讀。
一般資訊清單如下所示:
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-vector.svg",
"type": "image/svg+xml",
"sizes": "512x512"
},
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"id": "/?source=pwa",
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's the weather today?",
"short_name": "Today",
"description": "View weather information for today",
"url": "/today?source=pwa",
"icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
},
{
"name": "How's the weather tomorrow?",
"short_name": "Tomorrow",
"description": "View weather information for tomorrow",
"url": "/tomorrow?source=pwa",
"icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
}
],
"description": "Weather forecast information",
"screenshots": [
{
"src": "/images/screenshot1.png",
"type": "image/png",
"sizes": "540x720",
"form_factor": "narrow"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "720x540",
"form_factor": "wide"
}
]
}
主要資訊清單屬性
short_name
和name
您必須在資訊清單中至少提供一個 short_name
或 name
。如果
只要您同時提供這兩項資訊,系統會在應用程式安裝時使用 name
,而 short_name
為
用於使用者的主畫面、啟動器或其他位置
受到限制。
icons
當使用者安裝您的 PWA 時,您可以為瀏覽器定義一組圖示 分別用於主畫面、應用程式啟動器、工作切換器、啟動畫面和 和其他位置。
icons
屬性是圖片物件的陣列。每個物件都必須
包括 src
、sizes
屬性和圖片的 type
。使用條件
可遮蓋的圖示,有時也稱為自動調整
圖示,請將 "purpose": "any maskable"
新增至 icon
屬性。
針對 Chromium,您必須提供至少 192 x 192 像素的圖示和 512 x 512 像素的圖示。如果只提供這兩種圖示大小,Chrome 自動調整圖示以配合裝置尺寸。如果想 ,並依像素風格調整這些圖示,同時提供遞增的圖示 最低為 48 dp
id
id
屬性可讓您明確定義
應用程式。在資訊清單中新增 id
屬性,會移除
start_url
或資訊清單的位置,而且能夠更新
日後若需更多資訊,請參閲
使用網頁應用程式資訊清單 ID 屬性明確識別 PWA。
start_url
start_url
是必要屬性。可讓瀏覽器瞭解
應用程式應在啟動後啟動,並防止應用程式在啟動時啟動
也就是使用者將應用程式加入主畫面時所在的網頁。
您的 start_url
應將使用者直接導向應用程式,而非產品
到達網頁想想使用者會希望採取什麼行動
開啟應用程式並置入
background_color
出現 background_color
屬性時,啟動畫面會使用
這是我們第一次在行動裝置上推出應用程式
display
您可以自訂應用程式啟動時要顯示的瀏覽器使用者介面。適用對象
例如,您可以隱藏網址列和瀏覽器的使用者介面元素。遊戲
甚至可以啟動全螢幕display
屬性會採用以下其中一個值:
下列值:
屬性 | 行為 |
---|---|
fullscreen |
不需任何瀏覽器 UI 就能開啟網頁應用程式,並佔據所有 可用的顯示區域。 |
standalone |
開啟網頁應用程式,外觀與風格類似獨立的應用程式。應用程式執行
在瀏覽器視窗中獨立於瀏覽器視窗中,並隱藏標準圖片
瀏覽器的 UI 元素,例如網址列
![]() |
minimal-ui |
這個模式與 standalone 類似,但會提供
僅使用少量 UI 元素控制導覽功能
例如返回和重新載入按鈕
![]() |
browser |
標準瀏覽器體驗。 |
display_override
如要選擇網頁應用程式的顯示方式,請在資訊清單中將 display
模式設為
已說明。瀏覽器不必支援所有螢幕
但「必須」支援
規格定義的備用鏈
("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
)。如果他們不知道
都支援特定模式,就會在鏈結中改回下一個顯示模式。於
在極少數的情況下,這些備用方法可能會造成問題。舉例來說,開發人員無法
要求 "minimal-ui"
,而不強制返回 "browser"
螢幕
模式。"minimal-ui"
。目前行為也提高了
無法以回溯相容的方式導入新的顯示模式
因為它們在備用鏈中沒有空間
您可以運用 display_override
屬性自行設定備用序列。
瀏覽器在 display
屬性「之前」視為依據。其值是
系統會按照列出順序考量的字串序列,而第一個
支援的顯示模式如果不支援瀏覽器,瀏覽器會改回使用
評估 display
欄位如果沒有 display
欄位,瀏覽器
忽略 display_override
。
以下範例說明如何使用 display_override
。詳細資料:
「"window-control-overlay"
」超出範圍
。
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
載入這個應用程式時,瀏覽器會嘗試使用 "window-control-overlay"
首先。如果無法提供,則會改回採用 "minimal-ui"
,之後就會採用
來自 display
屬性的 "standalone"
。如果以上方法都不適用,
再回到標準備用鏈
scope
應用程式的 scope
是瀏覽器視為一部分的網址
scope
控制包含所有進入和結束的網址結構
指向應用程式,瀏覽器就會使用應用程式來判斷使用者何時離開
應用程式
scope
的其他注意事項:
- 如果資訊清單中沒有
scope
,則預設值為默示scope
是起始網址,但已移除其檔案名稱、查詢和片段。 scope
屬性可以是相對路徑 (../
) 或任何層級更高的路徑 可提高導覽涵蓋範圍的路徑 (/
) 就在網頁應用程式內start_url
必須位於範圍內。start_url
是相對於scope
屬性中定義的路徑。- 以
/
為開頭的start_url
一律是來源的根。
theme_color
theme_color
會設定工具列的顏色,且可反映在
工作切換器中的應用程式預覽theme_color
應與
文件標頭中指定的meta
主題顏色。
![採用自訂主題_color 的 PWA 視窗範例。](https://web.dev/static/articles/add-manifest/image/an-example-a-pwa-window-06989d8a3c54d.png?authuser=19&hl=zh-tw)
theme_color
的 PWA 視窗範例。
媒體查詢中的theme_color
您可以使用 media
屬性,在媒體查詢中調整 theme_color
meta
主題顏色元素。舉例來說,您可以為淺色模式定義一個顏色
另一個則是深色模式不過,您無法定義
資訊清單中的偏好設定若需更多資訊,請參閲
w3c/manifest#975 GitHub 問題。
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">
shortcuts
shortcuts
屬性是應用程式捷徑的陣列
物件,讓使用者快速存取應用程式中的主要工作。每位成員
是至少包含 name
和 url
的字典。
description
description
屬性說明應用程式的用途。
在 Chrome 中,所有平台的說明長度上限為 300 個字元。 如果說明長度超過上限,瀏覽器將以 省略符號。在 Android 上,說明也最多只能使用 上面有七行文字
screenshots
screenshots
屬性是代表應用程式的圖片物件陣列
常見用途每個物件都必須包含 src
,而 sizes
,以及圖片的 type
。form_factor
為選用屬性,
如要支援寬螢幕螢幕截圖,可以將其設為 "wide"
"narrow"
或僅針對窄版螢幕截圖。
在 Chrome 中,圖片必須符合下列條件:
- 寬度和高度必須介於 320 像素到 3840 像素之間。
- 尺寸上限不得大於最小尺寸長度的 2.3 倍 維度。
- 所有符合適用板型規格的螢幕截圖都必須相同
長寬比。
- 在 Chrome 109 中,只有
form_factor
設為"wide"
的螢幕截圖 不會在電腦上顯示
- 在 Chrome 109 中,只有
- 在 Chrome 109 中,
form_factor
設為"wide"
的螢幕截圖如下 在 Android 上會忽略但下列使用者仍會顯示沒有「form_factor
」的螢幕截圖: 具備回溯相容性
Chrome 電腦版會顯示至少一張及最多八張符合 這些條件。其餘將忽略。
Android 版 Chrome 會顯示至少一張和最多五張符合的螢幕擷取畫面 這些條件。其餘將忽略。
![在電腦和行動裝置上提供功能豐富的安裝使用者介面螢幕截圖。](https://web.dev/static/articles/add-manifest/image/screenshots-richer-insta-4ad995b153d76.jpeg?authuser=19&hl=zh-tw)
將網頁應用程式資訊清單新增至網頁
建立資訊清單後,請在網站的所有網頁中加入 <link>
標記
漸進式網頁應用程式。例如:
<link rel="manifest" href="/manifest.json">
測試資訊清單
如要驗證資訊清單設定是否正確,請使用右上角的「Manifest」窗格 ( Chrome 開發人員工具的「Application」面板。
![Chrome 開發人員工具中的應用程式面板,其中已選取資訊清單分頁。](https://web.dev/static/articles/add-manifest/image/the-application-panel-ch-36462ceb8c218.png?authuser=19&hl=zh-tw)
這個窗格提供清楚易懂的許多資訊清單版本 並確認所有圖片都能正常載入 正確做法。
行動裝置上的啟動畫面
應用程式首次在行動裝置上啟動時,瀏覽器可能需要一點時間 開始轉譯內容。與其顯示 這可能讓使用者誤以為應用程式無法運作 持續顯示啟動畫面,直到第一次繪製為止。
Chrome 會自動從 name
建立啟動畫面,
在資訊清單中指定的background_color
和icons
。營造流暢的氛圍
因此,請務必background_color
和載入網頁的顏色
Chrome 會選擇最符合裝置解析度的圖示 啟動畫面在大多數情況下,提供 192 像素和 512 像素的圖示就已足夠 但您可以提供其他圖示,讓模型更相符。
延伸閱讀
如要瞭解可加入網頁應用程式資訊清單的其他屬性,請前往 MDN 網頁應用程式資訊清單說明文件。