本文說明使用 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"
}
}
}