為了能出現在小工具主控區中，支援 Windows 小工具的應用程式必須向系統註冊其小工具提供者。 針對 Win32 應用程式，目前僅支援已封裝的應用程式，小工具提供者會在應用程式套件資訊清單檔案中指定其註冊資訊。 本文記載小工具註冊的 XML 格式。 如需 Win32 小工具提供者範例套件資訊清單的程式碼清單，請參閱範例一節。
應用程式延伸模組
應用程式套件資訊清單檔案支援 Windows 應用程式的許多不同延伸模組與功能。 應用程式套件資訊清單格式是由一組架構所定義，記載於套件資訊清單的結構描述參考。 小工具提供者會在 uap3:AppExtension 中宣告其註冊資訊。 延伸模組的 Name 屬性必須設定為 "com.microsoft.windows.widgets"。
小工具提供者應該包含 uap3:Properties 做為 uap3:AppExtension 的子系。 套件資訊清單架構不會強制執行 uap3:Properties 元素的結構，只會要求格式正確的 XML。 本文的其餘部分說明小工具主控區預期的 XML 格式，目的是要成功註冊小工具提供者。
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="com.microsoft.windows.widgets" DisplayName="WidgetTestApp" Id="ContosoWidgetApp" PublicFolder="Public">
<uap3:Properties>
<!-- Widget provider registration content goes here -->
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
元素階層
WidgetProvider
ProviderIcons
Icon
啟用
CreateInstance
ActivateApplication
定義
定義
Capabilities
功能
大小
ThemeResources
圖示
Icon
螢幕擷取畫面
Screenshot
DarkMode
圖示
Icon
螢幕擷取畫面
Screenshot
LightMode
圖示
Icon
螢幕擷取畫面
Screenshot
WidgetProvider
小工具提供者註冊資訊的根元素。
![Widget 面板中 [新增小工具] 對話框的螢幕快照。它會顯示兩個項目數據行，每個數據行都有圖示和應用程式名稱，加上加號，指出可以新增小工具](images/widget-picker.png)
WidgetProviderIcons
指定圖示來代表小工具提供者的應用程式。
啟用
指定小工具提供者的啟用資訊。 如果在資訊清單中同時指定 CreateInstance 和 ActivateApplication，則會優先使用 CreateInstance。
CreateInstance
CreateInstance 應指定給實作 IWidgetProvider 介面的 Win32 小工具提供者。 系統會透過呼叫 CoCreateInstance 來啟動介面。 ClassId 屬性會針對實作 IWidgetProvider 介面的 CreateInstance 伺服器指定 CLSID。
| 屬性 | 類型 | 必要 | 描述 | 預設值 |
|---|---|---|---|---|
| ClassId | GUID | Yes | 實作小工具提供者之 CreateInstance 伺服器的 CLSID。 | N/A |
ActivateApplication
指定 ActivateApplication 時，小工具提供者會透過命令列啟動，並使用以 base64url 編碼 JSON 字串格式提供的引數。 建議小工具提供者使用 CreateInstance 啟用類型。 如需 ActivateApplication 命令列格式的詳細資訊，請參閱小工具提供者 ActivateApplication 通訊協定。
定義
一個或多個小工具註冊的容器元素。
定義
表示單一小工具的註冊。
| 屬性 | 類型 | 必要 | 描述 | 預設值 |
|---|---|---|---|---|
| Id | string | Yes | 可識別小工具的識別碼。 這個值也會顯示在小工具選擇器的導覽列中。 小工具提供者的實作會使用此字串，來判斷或指定每個作業所參考的應用程式小工具。 對於應用程式資訊清單檔案內定義的所有小工具，此字串必須是唯一的。 | N/A |
| DisplayName | 字串 | Yes | 小工具主控區上顯示的小工具名稱。 | N/A |
| 說明 | string | Yes | 小工具的簡短描述。 | N/A |
| AllowMultiple | boolean | No | 如果只支援此小工具的一個執行個體，則設定為 false。 這是選用屬性，預設值為 true。 | true |
| IsCustomizable | boolean | No | Windows 應用程式 SDK 1.4 中引進。 如果您的應用程式支援小工具自訂功能，請設定為 true。 這會導致 [自訂小工具 ] 按鈕出現在小工具的省略符號功能表中。 | false |
| AdditionalInfoUri | 字串 | No | 當使用者單擊小工具框架的標題列，或單擊 其操作功能表的Powered by 元素時，可以使用的URI。 | N/A |
| ExcludedRegions | 字串 | No | 不應該使用小工具的區域清單。 Widget 可以指定 ExcludedRegions 或 ExclusiveRegions，但不能在單一小工具定義中同時指定這兩者。 屬性的值是兩個字元區域代碼的逗號分隔清單。 | N/A |
| ExclusiveRegions | 字串 | No | 應提供小工具的唯一區域清單。 Widget 可以指定 ExcludedRegions 或 ExclusiveRegions，但不能在單一小工具定義中同時指定這兩者。 屬性的值是兩個字元區域代碼的逗號分隔清單。 | N/A |
Capabilities
選擇性。 指定單一小工具的功能。 如果未宣告任何功能，預設會新增一個指定尺寸 "large" 的功能。
功能
指定小工具的功能。
大小
指定相關聯小工具的支援尺寸。
| 屬性 | 類型 | 必要 | 描述 | 預設值 |
|---|---|---|---|---|
| 名稱 | 字串 | Yes | 指定小工具的支援尺寸。 此值必須是下列其中一項："small"、"medium"、"large" | N/A |
ThemeResources
指定小工具的主題資源。
圖示
一個或多個 Icon 元素的容器元素。
Icon
必要。 指定小工具屬性區中顯示的圖示。
| 屬性 | 類型 | 必要 | 描述 | 預設值 |
|---|---|---|---|---|
| 路徑 | 字串 | Yes | 圖示影像檔案的套件相對路徑。 | N/A |
螢幕擷取畫面
必要。 指定一個或多個小工具的螢幕擷取畫面。
Screenshot
必要。 指定小工具的螢幕擷取畫面。 當使用者選取要新增至小工具主控區的小工具時，此螢幕擷取畫面會顯示在小工具主控區的 [新增 Widget] 對話方塊中。 如果您提供下列選用 DarkMode 或 LightMode 元素的螢幕擷取畫面，則小工具主控區將會使用符合目前裝置主題的螢幕擷取畫面。 如果您未提供目前裝置主題的螢幕擷取畫面，則會使用此 Screenshot 元素中提供的影像。 如需螢幕擷取畫面影像的設計需求，以及當地語系化螢幕擷取畫面命名慣例的相關資訊，請參閱整合小工具選擇器。
注意
在目前預覽版本，小工具面板的新增小工具對話方塊中，不會顯示小工具螢幕擷取畫面。
| 屬性 | 類型 | 必要 | 描述 | 預設值 |
|---|---|---|---|---|
| 路徑 | 字串 | Yes | 螢幕擷取畫面影像檔案的套件相對路徑。 | N/A |
| DisplayAltText | 字串 | No | 影像的替代文字，用於協助工具。 | N/A |
DarkMode
選擇性。 指定對應裝置啟用深色模式時的主題資源。 如果您在選用的 DarkMode 元素中指定一個或多個螢幕擷取畫面影像，當裝置處於深色模式時，小工具主控區將會選取這些螢幕擷取畫面。 如果您沒有提供深色模式影像，小工具主控區會使用上述必要的最上層 Screenshot 元素。 如需螢幕擷取畫面影像的設計需求，以及當地語系化螢幕擷取畫面命名慣例的相關資訊，請參閱整合小工具選擇器。
LightMode
選擇性。 指定對應裝置啟用淺色模式時的主題資源。 如果您在選用的 LightMode 元素中提供一個或多個螢幕擷取畫面影像，當裝置處於淺色模式時，小工具主控區將會選取這些螢幕擷取畫面。 如果您沒有提供淺色模式影像，小工具主控區會使用上述必要的最上層 Screenshot 元素。 如需螢幕擷取畫面影像的設計需求，以及當地語系化螢幕擷取畫面命名慣例的相關資訊，請參閱整合小工具選擇器。
範例
下列程式碼範例說明小工具套件資訊清單 XML 格式的使用方式。
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="com.microsoft.windows.widgets" DisplayName="Widget Test App" Id="ContosoWidgetApp" PublicFolder="Public">
<uap3:Properties>
<WidgetProvider>
<ProviderIcons>
<Icon Path="Images\StoreIcon.png" />
</ProviderIcons>
<Activation>
<!-- App exports COM interface which implements IWidgetProvider -->
<CreateInstance ClassId="XXXXXXXX-XXXX-XXXX-XXXX-D3397A3FF15C" />
</Activation>
<Definitions>
<Definition
Id="Weather_Widget"
DisplayName="Microsoft Weather Widget"
Description="Weather Widget Description"
AdditionalInfoUri="https://contoso.com/widgets/Weather"
ExclusiveRegions="US,UK"
AllowMultiple="true">
<Capabilities>
<Capability>
<Size Name="small" />
</Capability>
<Capability>
<Size Name="medium" />
</Capability>
<Capability>
<Size Name="large" />
</Capability>
</Capabilities>
<ThemeResources>
<Icons>
<Icon Path="Assets\icon.png" />
<Icon Path="Assets\icon.gif" />
</Icons>
<Screenshots>
<Screenshot Path="Assets\background.png" DisplayAltText ="For accessibility"/>
</Screenshots>
<!-- DarkMode and LightMode are optional -->
<DarkMode>
<Icons>
<Icon Path="Assets\dark.png" />
</Icons>
<Screenshots>
<Screenshot Path="Assets\darkBackground.png" DisplayAltText ="For accessibility"/>
</Screenshots>
</DarkMode>
<LightMode>
<Icons>
<Icon Path="Assets\light.png" />
</Icons>
<Screenshots>
<Screenshot Path="Assets\lightBackground.png"/>
</Screenshots>
</LightMode>
</ThemeResources>
</Definition>
</Definitions>
</WidgetProvider>
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
