Widget 提供者 ActivateApplication 協定

本文說明使用 ActivateApplication 啟用類型的元件提供者所使用的命令列啟用參數格式。

Important

Widget 提供者會在 Widget provider manifest 檔案中指定啟用方法,如 Widget provider 套件 manifest XML 格式所述。 建議元件提供者使用 CreateInstance 啟用型態,並以 IWidgetProvider 介面方法回應元件主機請求,而非使用 ActivateApplication 啟用方法。 本文中的資訊僅為求完整而提供,不建議大多數小工具提供者實作採用。

ActivateApplication 與 base64url 編碼中的參數字串

當 widget 提供者被啟用時,命令列在命令列參數中 --widget-call= 編碼前會有前綴。

--widget-call=[base64url]

例如,在 base64url 部分中

--widget-call=ewogICAgIldpZGdldENhbGwiOiJDcmVhdGVXaWRnZXQiLAogICAgIldpZGdldENvbnRleHQiOnsKICAgICAgICAiSWQiOiI5ODU4MjEwOS1jNmJmLTQzNzItODlkNi04OWY1N2ViNzU0ZjYiLAogICAgICAgICJEZWZpbml0aW9uSWQiOiJQV0FfQ291bnRpbmdfV2lkZ2V0IiwKICAgICAgICAiU2l6ZSI6IkxhcmdlIgogICAgfQp9

被解碼為

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

命令列格式細節

JSON 命令列代表對應 IWidgetProvider 方法的呼叫。 以下偽程式碼總結了這些方法;它不是一個可編譯的介面宣告。

    interface IWidgetProvider
    {
        void CreateWidget(WidgetContext widgetContext);
        void DeleteWidget(String widgetId, String customState);
        void OnActionInvoked(WidgetActionInvokedArgs actionInvokedArgs);
        void OnWidgetContextChanged(WidgetContextChangedArgs contextChangedArgs);
        void Activate(WidgetContext widgetContext);
        void Deactivate(String widgetId);
    }

每次啟用代表一個方法呼叫。 JSON 物件有一個 WidgetCall 值,其中包含方法名稱,而屬性則包含呼叫的資料。 以下範例展示了傳輸屬性名稱,包括代表回呼引數物件的 Args。

對於 WidgetContext,JSON 包含 Id、DefinitionId 和 Size。 Id 識別一個小工具實例,並且 DefinitionId 識別其資訊清單定義。 JSON 以字串表示 Size,例如 "Large";實際的 WidgetContext.Size API 屬性是 WidgetSize 枚舉,而非字串。

附註

元件提供者應忽略意外參數值,以處理未來新增參數的情況。

widget 提供者 CreateWidget 的 API 呼叫會被封組為 Json 物件:

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

處理 ActivateApplication 參數時,請使用此處所示的 JSON 傳輸格式,而非將 JSON 視為 WinRT 介面宣告。

編組物件範例

建立 Widget JSON 物件

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

刪除 Widget Json 物件

{
  "WidgetId": "1AC74363-177B-4CD2-995F-3B25AEEA3FF4",
  "WidgetCall": "DeleteWidget",
  "CustomState": "usedata"
}

OnActionInvoked Json Object

{
    "WidgetCall": "OnActionInvoked",
    "Args":{
        "Verb": "Verb String",
        "Data": "Data Details",
        "CustomState": "usedata",
        "WidgetContext": {
            "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
            "DefinitionId":"PWA_Counting_Widget",
            "Size":"Large"
        }
    }
}

啟用 Json 物件

{
    "WidgetCall": "Activate",
    "WidgetContext": {
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

停用 JSON 物件

{
    "WidgetCall": "Deactivate",
    "WidgetId":"98582109-c6bf-4372-89d6-89f57eb754f6"
}

OnWidgetContextChanged JSON 物件

例如,當 WidgetSize 變換為 Medium時,會觸發一個 WidgetContextChanged 事件。

{
  "WidgetCall": "OnWidgetContextChanged",
  "Args":{
    "WidgetContext":{
            "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
            "DefinitionId":"PWA_Counting_Widget",
            "Size":"Medium"
        }
  }
}