共用方式為

在 Windows 上啟用 PWA 的應用程式動作

你可以為 Windows 框架上的 App Actions 撰寫並測試應用程式動作，針對你所建立的 Progressive Web 應用程式 (PWA) 。 Windows 上的應用程式動作是 Windows 應用程式可實作並登錄的單一行為單元。 App Action 可從其他應用程式與體驗中存取，無縫整合進使用者工作流程。

應用程式會建立並註冊每個應用程式動作，然後 Windows 應用程式與經驗能在使用者工作流程中與上下文相關的時間與地點向使用者推薦已註冊的應用程式動作。

你可以建立 Windows App 動作，以提升應用程式功能的可發現性與互動度。

另請參閱:

詳細內容：

Windows App Actions 框架是用來暴露和執行應用程式關鍵功能，而非像開啟右鍵選單 (右鍵選單) 這類通用的使用者操作。 請參閱 Windows 上的應用程式動作總覽中的「應用程式動作推薦情境」。

在動作定義清單中定義應用程式動作

你可以在動作定義清單檔案 (ActionsManifest.json 如) 中定義 PWA 所支援的應用程式動作。 這是一個用於 Windows 應用程式動作的動作定義 JSON 檔案。

本文說明如何撰寫一個應用程式動作，使用範例 PWA、 wami（網頁應用程式來操作圖片）。 wami 示範支援影像處理任務，例如調整大小或套用後製風格。

以下範例動作定義清單檔案 (名為 ActionsManifest.json) ，定義了 wami 範例應用程式中繪畫功能中的 繪圖 應用程式動作。 Paint 功能由 Paint App Action 參考，會產生油畫風格的圖像。

{
   "version": 1,
   "actions": [{
      "id": "Wami.Paint",
      "description": "Convert the image to oil paint style",
      "kind": "Search",
      "inputs": [{
         "name": "File",
         "kind": "Photo"
        }],
      "outputs": [],
      "invocation": {
         "type": "Uri",
         "uri": "web+wami://paint"
      },
      "inputCombinations": [{
         "inputs": [ "File" ],
         "description": "Photo to be converted to oil paint style."
      }]
   }]
}

作為輸入， Paint App 動作會接受使用者所選擇的圖片檔案。

Paint App 動作會回傳風格化的輸出。

動作定義清單中支援的屬性

動作定義清單檔案 (，例如 ActionsManifest.json) ，是一個描述性檔案，Windows App Actions Runtime 用於應用程式，用以宣告該應用程式所支援的應用程式動作。

關於每個支援的 JSON 屬性的定義，請參閱 Windows 應用程式動作的動作定義 JSON 結構中的動作定義 JSON 屬性。

在 Invocation下，僅支援該 uri 類型。 此 com 類型不適用於 PWA。

支援的 PWA 應用程式動作實體類型

在動作定義清單檔案 (如 ActionsManifest.json) 中， ActionEntityKind 列舉指定了 Windows 應用程式動作所支援的實體類型。

在 JSON App Action 定義的語境中，實體類型是字串字面，且具有大寫區分。 支援的實體列舉於 Windows 應用程式動作的 Action 定義 JSON 架構中的 ActionEntityKind 枚舉中。

StreamingText RemoteFile且尚未支援 PWA。 關於 File、 Photo和 DocumentText 實體類型，請參閱 Windows 應用程式動作的動作定義 JSON 架構中的實體屬性。

PWA 如何透過 URI 啟動啟動

當 PWA 的應用程式動作被呼叫時，Windows 會透過自訂協定 URI 啟動該應用程式動作。 PWA 必須透過 protocol_handlers PWA 網頁應用程式清單中的欄位（如 Demos/wami/manifest.json）註冊自訂協定處理。

Windows 的方法 LaunchUriAsync(Uri, LauncherOptions, ValueSet) 被 Action Framework 用於 URI 啟用。 LaunchUriAsync 不會回傳值或錯誤狀態。

uri 在行動定義中 manifest

使用自訂協定 URI，而非 HTTPS URI。

對於擁有多個應用程式動作的 PWA，請使用以下語法：

"uri": "web+{app name}://{custom action name}"

例如：

"uri": "web+wami://paint"

上述這行在動作 定義清單中的「定義應用程式動作」中呈現。

接收 ValueSet 資料並將其映射到共享目標

啟動的協議 URI 會映射到 url 分享目標資料的欄位。

輸入 ValueSet 會被轉換成有效的 JSON 字串，並映射到 text share 目標資料的欄位。 這讓 Microsoft Edge 能夠判斷協定處理器的啟動代表應用程式動作。

應用程式的網頁應用程式清單 (如 Demos/wami/manifest.json) 必須正確設定欄位 share_target ，才能啟用作為應用程式動作的共享目標。 請參考 share_target 下方網頁應用程式清單。

你的 PWA 支援應用程式動作的前提條件

要正確整合您的 PWA 與 Windows 上的應用程式動作框架，以下網頁應用程式清單成員是必要的：

  • share_target
  • protocol_handlers
  • launch_handler

share_target 在網頁應用程式清單中

PWA 若要使用 App Actions，該 share_target 欄位必須存在於 PWA 的網頁應用程式清單檔案中，例如 Demos/wami/manifest.json。

  • 方法必須是「POST」。
  • enctype必須是multipart/form-data。
  • text 以及 url 必須 params 支援應用程式動作。
  • files 是可選的。 如果你不希望 PWA 支援一般的分享目標功能，可以省略files。

範例 share_target 聲明，來自 Demos/wami/manifest.json：

"share_target": {
   "action": "./share-target",
   "method": "POST",
   "enctype": "multipart/form-data",
   "params": {
      "title": "title",
      "text": "text",
      "url": "url"
   }
}

另請參閱:

處理應用程式動作的實體

應用程式動作的實體會透過 POST 分享資料傳遞給 PWA。 要處理 POST 分享資料，你可以使用或結合以下方法：

以下程式碼來自 Wami 示範中 Demos/wami/sw.js中範例服務工作者處理程式，以支援應用程式啟動應用程式動作：

// Extract data
const data = {
   text: formData.get('text') || '',
   url: formData.get('url') || ''
};
const files = formData.getAll('windowsActionFiles');

鑰匙說明 formData ：

  • 簡訊： 一個列出所有輸入實體的 JSON 字串。 輸入參數值必須與你在 PWA 網頁應用程式清單 share_target.params.text中設定的值相同。 文字中包含的檔案 路徑是安全的 。 為了保護使用者隱私，Edge 會在用戶提供的路徑資訊到達你的服務人員手中前將其清除，只留下檔案名稱。

  • 網址： 例如 web+wami://paint ，在範例) 中，URI 協定 (，該協定標示了觸發啟動的應用程式動作。 輸入參數值必須與你在 PWA 網頁應用程式清單 share_target.params.url中設定的值相同。

  • 檔案： 檔案物件附加於應用程式動作呼叫。

protocol_handlers 在網頁應用程式清單中

PWA 若要使用 App Actions，該 protocol_handlers 欄位必須存在於 PWA 的網頁應用程式清單檔案 (，例如 Demos/wami/manifest.json) 。 欄位 protocol_handlers.protocol 必須與動作定義清單檔案的第一部分 invocation.uri 相符， (如 ActionsManifest.json) 。

範例 protocol_handlers 聲明，來自 Demos/wami/manifest.json：

"protocol_handlers": [{
   "protocol": "web+wami",
   "url": "./?url=%s"
}]

來自 ActionsManifest.json的匹配invocation.uri場：

"invocation": {
   "type": "Uri",
   "uri": "web+wami://paint"
},

上述片段在動作 定義清單中的「定義應用程式動作」中以上下文形式呈現。

另請參閱:

launch_handler 在網頁應用程式清單中

如果你想保留單一 PWA 視窗，可以像你 PWA 網頁應用程式清單檔案 (launch_handlernavigate-existing 設定，例如 Demos/wami/manifest.json) 。

範例聲明：

"launch_handler": {
   "client_mode": " navigate-existing"
}

上述程式碼不存在 於 Demos/wami/manifest.json 裡。

在 Edge Stable 中打包一個儲存 PWA

接著，你的 PWA 需要以 Microsoft Store PWA 的形式打包，並由 Windows App Actions 框架呼叫。

要將你的 PWA 打包成 Microsoft Store 的 PWA：

  1. 打包你的 PWA 進行 PWABuilder.com;請參閱「將 PWA 打包至商店 」中的「 發佈 PWA 至 Microsoft Store」。

  2. 在 所有設定中，往下滑到底部的 「動作」——啟用動作 。

  3. 確保你的 PWA 網頁應用程式清單檔案 (像是 Demos/wami/manifest.json) 有 protocol_handlers 欄位 share_target 。 PWABuilder.com 會執行檢查，如果應用程式的網頁應用程式清單中缺少任一欄位，啟用 動作 的勾選框會變成灰色。

  4. 在 動作 區塊點選 選擇檔案，並上傳你為 PWA 準備的動作定義清單檔案 (，例如 ActionsManifest.json 你為 PWA 準備的) 。

  5. 點擊 下載 按鈕。

  6. 解壓你的下載壓縮檔。 安裝方式是執行 install.ps1。

  7. 點擊 PWA 圖示啟動你的 PWA。

  8. 請依照下方 的「PWA 測試應用程式動作」在本地測試您的 PWA 動作，以驗證其功能。

  9. 打開動作定義清單檔案 (，例如 ActionsManifest.json 你在 PWAbuilder.com 包裝時使用的) 。

  10. 將每個應用程式動作的初始可用性設為 false，詳見「在 Windows 應用程式動作的可切換性中設定初始可用性」。

    在發布您的方案前，我們建議先採取上述步驟。 如果你沒有將應用程式動作的初始可用性設為 false，你的動作只有在使用者手動進入 edge://flags Microsoft Edge 並啟用功能標誌 #edge-app-actions-on-windows-for-web-apps時才會生效。

    將初始可用性 false 設為 是必要的，因為 Microsoft Edge 在 Windows 上 PWA 中支援的應用程式動作是由功能旗標 #edge-app-actions-on-windows-for-web-apps控制，且預設是被禁用的，因為該功能目前處於開發者試用階段。

    當功能旗標 #edge-app-actions-on-windows-for-web-apps 於 2025) (正式推出時， Microsoft Edge 會自動將您在動作定義清單檔案中定義的動作從 Disabled 切換到 ， Enabled讓終端使用者無需額外修改即可使用應用程式的動作。

  11. 發佈你的 PWA，如同「 向 Microsoft Store 發佈 PWA」一文所述。

在 Edge Canary 打包商店 PWA

Edge Canary 預覽了尚未在穩定版中提供的功能。

如果你想在 Edge Canary 中試用最新的應用程式動作功能，你可以將你的 PWA 打包在 Edge Canary，如下：

  1. 安裝 Edge Canary 並升級到最新版本。

  2. 取得你的 PWA 的 套件 ID、 發行商 ID 和 出版商顯示名稱 ;詳見 「發佈 PWA 至 Microsoft Store」。

  3. 請前往 PWABuilder.Windows.Chromium 測試器。

  4. 在輸入框輸入你的 PWA 設定，針對以下欄位輸入：

    • name：你PWA的名字。
    • packageId： 如果你不願意將 Edge Canary 版本的應用程式發佈到商店，則不需要;可以是空字串。
    • url： 你的 PWA 網址。
    • publisher.displayName出版社名稱。 如果你不願意將 Edge Canary 版本的應用程式發佈到商店，就不需要了;可以是空字串。
    • publisher.commonName：你的出版商ID。 如果你不願意將 Edge Canary 版本的應用程式發佈到商店，就不需要了;可以是空字串。
    • startUrl：你的PWA的 startUrl。

    範例 JSON 清單，你可以複製並貼上到 PWABuilder.Windows.Chromium 測試器的文字欄位：

    {
   "name": "Wami for Canary",
   "packageId": "",
   "url": "https://microsoftedge.github.io/Demos/wami",
   "version": "1.0.2",
   "allowSigning": true,
   "classicPackage": {
      "generate": true,
      "version": "1.0.0"
   },
   "publisher": {
      "displayName": "",
      "commonName": ""
   },
   "edgeChannel": "canary",
   "appUserModelId": "Microsoft.Canary_8wekyb3d8bbwe!MSEDGE",
   "generateModernPackage": true,
   "resourceLanguage": "EN-US",
   "startUrl": "https://microsoftedge.github.io/Demos/wami"
}

    將上述屬性替換成你應用程式的實際屬性。

  5. 上傳動作定義清單檔案 (如 ActionsManifest.json) ，然後點擊 下載 按鈕。

  6. 你的下載是一個 .zip 包含檔案（如 和 .msix.msixbundle 檔案）的壓縮檔。 解壓縮後直接執行 install.ps1 安裝你的 PWA。

  7. 點擊你的 PWA 圖示。

    你的 PWA 開始。

  8. 啟動 Edge Canary，然後前往 edge://apps。

    你的PWA已經列出了。

  9. 點擊 詳情 按鈕。

    你的 PWA 顯示已安裝於 Microsoft Store。

你的 PWA 現在已經在 Edge Canary 安裝成商店 PWA。

PWA 的測試應用程式動作

要測試你的 PWA 應用程式動作：

  1. 請確保您的 PWA 已如上述章節所討論，成功設定與打包。

  2. 確保 Windows 已更新以支援應用程式動作;詳見 Windows 11 Insider 預覽版本 26120.4151 (Beta 頻道) 。

  3. 確保 Microsoft Edge 已更新到最新版本，並成功安裝你的 PWA;請參見上方 「在 Edge Stable 中打包一個儲存 PWA 」或 「在 Edge Canary 打包一個儲存 PWA」。

  4. 啟動 Edge Canary 或 Edge Stable， (你安裝 PWA 的頻道) 。

  5. 前往 edge://flags搜尋 應用程式動作，並找到 「在 Windows 上啟用應用程式動作」這個網頁應用程式的條目。 (旗幟名稱為 #edge-app-actions-on-windows-for-web-apps.)

  6. 狀態改為 啟用，然後點擊右下角的 重新啟動 按鈕。

  7. 啟動你的 PWA。

    你的 PWA 必須至少啟動一次，以初始化 App Action 的 PWA，然後才會被 App Actions 執行時呼叫。

  8. 使用 App Actions 測試遊樂場應用程式來測試你的 PWA 應用程式。

  9. 新增一個該應用程式動作所需的實體。 例如，如果 App Action 正在處理圖片，請新增一張圖片。 然後執行應用程式動作。

    PWA 啟動並執行應用程式動作。

另請參閱

Windows 相關文章：

地點：

MDN：

Demos repo：

  • Last updated on