scope

語法

/* Absolute URL */
"scope": "https://example.com/myapp/"

/* Relative URL */
"scope": "/myapp/"

/* Scope limited to a specific directory */
"scope": "/myapp/dashboard/"

值

scope

表示 URL 的字串。URL 可以是絕對的也可以是相對的。如果值為相對值，則會相對於清單檔案的 URL 進行解析。

如果清單中未指定 scope，或者值無效（即不是字串、不是有效 URL，或者 start_url 不在指定的 scope 內），則有效 scope 將被設定為 start_url 值，並去除其檔名、查詢和片段。

描述

scope 成員定義了屬於你的 Web 應用已安裝體驗的 URL。瀏覽器使用 scope 來確定一個頁面是否在你的 Web 應用的 應用上下文 內。

Scope 內外行為

如果一個 URL 的路徑以 scope 中定義的 URL 路徑開頭，則該 URL 被視為“在 scope 內”。例如，如果 scope 設定為 /app/，那麼 URL /app/、/app/page.html 和 /app/dashboard/index.html 都被視為在 scope 內，而 / 或 /page.html 則不在。

當用戶開啟你已安裝的 Web 應用時，他們會看到一個類似應用介面的體驗。對於 scope 內的頁面，瀏覽器會維護應用上下文並保留類似應用介面的體驗。當用戶導航到應用 scope 外的頁面時，他們仍然會大致體驗到類似應用介面的體驗；但是，在這些頁面上，瀏覽器會顯示額外的 UI 元素，如 URL 欄。這有助於使用者瞭解他們正在檢視的頁面超出了應用定義的 scope。

考慮一個用於探索徒步小徑的 Web 應用，其目錄結構如下

web-app/
├── manifest.json
├── trails/
│   ├── index.html
│   ├── trail-list.html
│   ├── settings/
│   │   └── index.html
│   └── saratoga-gap-trail.html
├── blog/
│   └── index.html

當 scope 設定為 /trails/ 時

• 在檢視 /trails/ 下的頁面和子目錄（如 trail-list.html 和 /trails/settings/index.html）時，使用者將體驗到類似應用介面的體驗，而沒有瀏覽器控制元件（左側影像）。
• 當導航到子目錄中的頁面（如 /blog/）時，這些頁面超出了應用的 scope，但應用介面的體驗仍然存在，只是使用者會看到網站地址和其他瀏覽器控制元件（右側影像）。

Scope 內頁面	Scope 外頁面

Scope 對深度連結頁面的影響

其他應用可以直接深度連結到你的 Web 應用的特定頁面。scope 成員會影響這些深度連結頁面的顯示方式，但它不是深度連結工作的必需項。

以之前探索徒步小徑的 Web 應用為例，其中 scope 設定為 /trails/

• 如果在社交媒體上分享到 https://trailnav.app/trails/saratoga-gap-trail.html 的連結，已安裝 Trail Navigator 應用的使用者將會在應用的介面中檢視此頁面，而沒有瀏覽器控制元件。
• 如果分享的連結是 https://trailnav.app/blog/trail-safety.html，這些使用者將會在類似應用介面的體驗中檢視部落格頁面，但會顯示網站地址和瀏覽器控制元件，因為該頁面超出了應用定義的 scope。

這種行為即使在透過外部連結訪問應用頁面時，也能幫助使用者瞭解他們檢視的頁面是否在應用 scope 內或外。

Fallback Scope 行為

如果 start_url 不是 scope URL 的子集，則 scope 無效。例如：

• 有效：scope 為 /app/，start_url 為 /app/home.html。
• 無效：scope 為 /app/，start_url 為 /index.html。

如果 scope 缺失或無效，它將預設為 start_url 值，並去除其檔名、查詢和片段。請注意，如果 start_url 也未定義（或無效），它將預設為連結到清單的頁面。這確保了預設情況下，scope 將從觸發安裝的頁面開始。

例如

• 如果 start_url 是 https://example.com/app/index.html?user=123#home，則 scope 將是 https://example.com/app/。
• 如果 start_url 是 /pages/welcome.html，則 scope 將是同一域下的 /pages/。
• 如果 start_url 是 /pages/（尾部斜槓很重要），則 scope 將是 /pages/。

如果你依賴 scope 的 fallback 行為，請確保你應用中所有頁面的 URL 都以 start_url 的父路徑開頭。為了避免以這種方式確定 scope 的問題，建議在你的清單檔案中明確指定 scope。

Scope 匹配機制

scope URL 的字串匹配採用簡單的字首匹配，而不是路徑結構。例如，如果 scope 設定為 /prefix，它將匹配以 /prefix 開頭的 URL，包括 /prefix-of/index.html 和 /prefix/index.html。請注意，/prefix-of/index.html 匹配，即使 prefix-of 與 scope /prefix 不是精確匹配。

因此，建議定義一個以 / 結尾的 scope。將 scope 設定為 /prefix/ 可確保它只匹配 /prefix/ 目錄內的頁面，從而防止意外匹配。

示例

為 scope 指定絕對 URL

假設你的 Web 應用的清單檔案連結自 https://hikingapp.com/index.html，並且你希望 scope 包含所有子目錄。你可以使用與清單檔案 URL 同源的絕對 URL 指定此 scope，如下所示。這確保了像 https://hikingapp.com/store 和 https://hikingapp.com/company 這樣的頁面屬於你的 Web 應用。

{
  "scope": "https://hikingapp.com/"
}

為 scope 指定相對 URL

如果你的清單檔案的 URL 是 https://hikingapp.com/resources/manifest.json，並且你希望 scope 是 https://hikingapp.com/app/，你可以將其定義為相對 URL

{
  "scope": "../app/"
}

為網站的特定部分定義 Web 應用

如果你有一個包含多個部分的網站，但你想讓你的 Web 應用專注於一個特定部分，你可以將 scope 定義為

{
  "name": "My Hiking Web App",
  "start_url": "https://hikingapp.com/store/",
  "scope": "https://hikingapp.com/store/"
}

透過這種設定，像 https://hikingapp.com/store/products 這樣的頁面屬於你的 Web 應用，但 https://hikingapp.com/company/ 超出了你 Web 應用的 scope。對於 scope 外的 URL，瀏覽器可能會顯示不同的 UI 元素，讓使用者知道他們已離開應用的 scope。

規範

瀏覽器相容性

另見

• start_url manifest member
• 應用程式上下文