小工具提供者 ActivateApplication 通訊協定

發行項
10/05/2023

本文說明使用 ActivateApplication 啟用類型的小工具提供者命令列啟用參數的格式。

重要

小工具提供者會在小工具提供者資訊清單檔案中指定啟用方法，如小工具提供者封裝資訊清單 XML 格式所述。建議小工具提供者使用 CreateInstance 啟用類型，並使用 IWidgetProvider 介面方法回應小工具主機要求，而不是使用 ActivateApplication 啟用方法。本文中的資訊是為了完整性而提供，不建議大部分的小工具提供者實作使用。

ActivateApplication 和 base64url 編碼中的引數字串

當小工具提供者啟用時，命令列會在命令列引數中的 base64url 編碼之前加上 --widget-call= 前置詞。

--widget-call=[base64url]

例如，在下列項目中的 base64url 元件

--widget-call=ew0KICAgICJXaWRnZXRDYWxsIjoiQ3JlYXRlV2lkZ2V0IiwNCiAgICAiV2lkZ2V0Q29udGV4dCI6ew0KICAgICAgICAiSWQiOiI5ODU4MjEwOS1jNmJmLTQzNzItODlkNi04OWY1N2ViNzU0ZjYiLA0KICAgICAgICAiRGVmaW5pdGlvbk5hbWUiOiJQV0FfQ291bnRpbmdfV2lkZ2V0IiwNCiAgICAgICAgIlNpemUiOiJMYXJnZSINCiAgICB9DQp9

解碼為

{
    "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);
        void OnActionInvoked(WidgetCallInvokedArgs actionInvokedArgs);
        void OnWidgetContextChanged(WidgetContextChangedArgs contextChangedArgs);
    }

每個啟用都代表一個方法呼叫。 Json 物件具有具有方法名稱的 WidgetCall 值，然後每個參數的值，名稱是參數名稱，但全部大寫。每個參數都會以一對<變數名稱、值> 對應至 json 物件。例如，針對 CreateWidget 方法的 WidgetContext widgetContext 參數，WidgetContext 的定義如下:

    runtimeclass WidgetContext
    {
        String Id { get; };
        String DefinitionId{ get; };
        String Size { get; };
    };

注意

小工具提供者應該忽略非預期的參數值，以處理未來新增其他參數的案例。

小工具提供者 CreateWidget API 呼叫會封送處理至 Json 物件:

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

物件一律會包含 WidgetCall 值和 IWidgetProvider 方法所指定的所有參數值。

封送處理物件範例

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

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

OnActionInvoked Json 物件

{
    "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 已變更為 [中]。在 SV2 中，WidgetSize 是唯一觸發 WidgetCoNtextChanged 的項目。

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

共用方式為