小组件提供程序 ActivateApplication 协议

项目
09/02/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 更改为 Medium。在 SV2 中，WidgetSize 是唯一触发 WidgetContextChanged 的项。

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

通过