使用 Web 應用程式指令清單將 PWA 整合到 OS 中

  • 發行項

漸進式 Web 應用程式 (PWA) 必須有 Web 應用程式指令清單，才能定義 PWA 如何與操作系統整合 (OS) 。 本文說明什麼是 Web 應用程式指令清單，以及 Web 應用程式指令清單包含哪些必要和選擇性數據。

Web 應用程式指令清單檔案會控管您的 PWA 在裝置上安裝時的外觀和行為。 Web 應用程式指令清單會提供資訊，例如您的應用程式名稱、在系統功能表中代表您應用程式的圖示檔案位置，以及操作系統在標題列中使用的主題色彩。

Web 應用程式指令清單是 JSON 檔案，必須使用指令清單連結從網站的 HTML 頁面參考。 在網站 HTML 頁面的 和 </head> 標記之間<head>插入下列程式代碼，以連結至您的指令清單檔案：

<link rel="manifest" href="/manifest.json">

Web 應用程式指令清單檔案類型

Web 應用程式指令清單的內容必須是有效的 JSON，但擴展名可以是 .json 或 .webmanifest。

如果您選擇使用 .webmanifest 擴充功能，請確認您的 HTTP 伺服器使用 MIME 類型為它 application/manifest+json 提供服務。

指令清單成員

指令清單檔案至少應包含下列指令清單成員：

{
    "name": "My Sample PWA",
    "lang": "en-US",
    "start_url": "/"
}

以下是包含更多成員的指令清單檔案範例：

{
    "name": "My Sample PWA",
    "lang": "en-us",
    "short_name": "SamplePWA",
    "description": "A sample PWA for testing purposes",
    "start_url": "/",
    "scope": "/",
    "display": "standalone",
    "theme_color": "#2f3d58",
    "background_color": "#2f3d58",
    "orientation": "any",
    "icons": [
        {
            "src": "/icon512.png",
            "sizes": "512x512"
        }
    ]
}

您可以使用其他指令清單成員進一步自訂 PWA，如下所示：

成員 描述
name 應用程式的名稱，由作業系統用來顯示在應用程式圖示旁邊。
short_name 當 沒有足夠的空間可供 使用時，這可以用來顯示應用程式的 name名稱。
description 應用程式的描述。
categories 應用程式所屬的類別清單。
icons OS 在不同內容中使用的圖示影像對象陣列。
screenshots 螢幕快照影像對象的陣列，也由操作系統在不同內容中使用。
start_url 操作系統啟動應用程式時應巡覽至的慣用URL。
scope 定義應用程式的瀏覽範圍。 在此範圍之外，流覽過的頁面會還原為一般網頁，而非 PWA。 預設為 start_url。
display 應用程式看起來應該的樣子。 這會變更向用戶顯示多少瀏覽器 UI。
display_override 根據裝置支援的內容，用來判斷應用程式的慣用顯示器。
theme_color 應用程式的預設主題色彩。 這會影響OS顯示網站的方式。
background_color 套用樣式表單之前，啟動應用程式之視窗的背景色彩。
orientation 在支援裝置上，這會定義應用程式 (的預設方向，例如橫向或直向) 。
protocol_handlers 與應用程式相關聯的預先定義或自定義 URI 通訊協定配置清單。
shortcuts 使用者在應用程式圖示上按下滑鼠右鍵或長按即可執行的一般工作清單。
share_target 應用程式透過 [OS 共用] 對話框共用內容時所接受的數據類型。
file_handlers 應用程式可以啟動的檔案類型。

若要深入瞭解指令清單成員，請參閱 MDN 上的 Web 應用程式指令清單 。

處理特定通訊協定配置

您可以將 PWA 註冊為通訊協定處理程式。 當使用者按兩下使用應用程式註冊之通訊協定設定的連結時，您的應用程式會自動啟動。 這可讓用戶輕鬆地彼此共用應用程式特定元件或功能的連結。

若要註冊為通訊協定處理程式，請使用指令 protocol_handlers 清單成員：

{
    "protocol_handlers": [
        {
            "protocol": "mailto",
            "url": "/newEmail?to=%s"
        }
    ]
}

若要深入瞭解，請 參閱處理漸進式 Web Apps 中的通訊協定。

使用快捷方式快速存取功能

大部分的操作系統都會使用連線到應用程式圖示的右鍵功能表上的快捷方式，快速存取主要應用程式功能。 若要在 PWA 中使用快捷方式，請在 Web 應用程式指令清單中包含 shortcuts 成員。

下列程式代碼示範如何在 Web 應用程式指令清單中定義快捷方式。

"shortcuts": [
    {
        "name": "Play Later",
        "description": "View the list of podcasts you saved for later",
        "url": "/play-later",
        "icons": [
            {
                "src": "/icons/play-later.svg",
                "type": "image/svg+xml",
                "purpose": "any"
            }
        ]
    },
    {
        "name": "Subscriptions",
        "description": "View the list of podcasts available in your subscription",
        "url": "/subscriptions?sort=desc"
    }
]

若要深入瞭解，請 參閱定義應用程式快捷方式。

將您的應用程式識別為共享目標

若要讓用戶能夠快速地與原生應用程式共用連結和檔案，請在 Web 應用程式指令清單中使用 share_target 物件。 頁面 action 類似於表單。 在物件中 share_target ，您會定義 action 頁面，以及您預期要傳遞至頁面的 action 參數。

"share_target": {
    "action": "/share.html",
    "params": {
        "title": "name",
        "text": "description",
        "url": "link"
    }
}

上述 share_target 物件會 /share.html 建立 為 action 共享的頁面。 這個範例也會定義三個會傳遞至該 action 頁面的參數： title、 text和 url。

若要深入瞭解如何使用共用目標功能，請參閱 與其他應用程式共享內容。

將您的應用程式與檔案產生關聯

當 PWA 註冊為特定檔案類型的檔案處理程式時，作業系統可以在使用者開啟這些檔案時自動啟動應用程式，類似於Microsoft Word 處理 .docx 檔案的方式。 處理檔案的 PWA 對使用者而言更具有原生性，而且在操作系統中更妥善地整合。

若要處理檔案，請列出您想要與應用程式相關聯的檔案mime類型和擴展名，並定義您的應用程式應該以下列方式啟動的URL：

{
    "file_handlers": [
        {
            "action": "/openFile",
            "accept": {
                "text/*": [
                    ".txt"
                ]
            }
        }
    ]
}

然後使用 window.launchQueue() 方法來處理檔案：

if ('launchQueue' in window) {
    launchQueue.setConsumer(launchParams => {
        // Do something with launchParams.files ...
    });
}

若要深入瞭解，請 參閱處理漸進式 Web Apps 中的檔案。