小组件提供程序 ActivateApplication 协议

本文介绍使用 ActivateApplication 激活类型的小组件提供程序的命令行激活参数的格式。

Important

小组件提供程序在小组件提供程序清单文件中指定激活方法,如 小组件提供程序包清单 XML 格式中所述。 建议小组件提供程序使用 CreateInstance 激活类型,并使用 IWidgetProvider 接口方法而不是 ActivateApplication 激活方法响应小组件主机请求。 本文中的信息出于完整性提供,不建议用于大多数小组件提供程序实现。

ActivateApplication 和 base64url 编码中的参数字符串

激活小组件提供程序时,命令行将在命令行参数中的 --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 枚举,而不是字符串。

注释

小组件提供程序应忽略意外的参数值来处理将来会添加其他参数的情况。

小组件提供程序 CreateWidget API 调用封送给 Json 对象:

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

处理 ActivateApplication 参数时,请使用此处显示的 JSON 传输格式,而不是将 JSON 视为 WinRT 接口声明。

封送对象示例

创建组件 JSON 对象

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

删除小组件 Json 对象

{
  "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时,会触发WidgetContextChanged事件。

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