小组件提供程序包清单 XML 格式

项目
09/25/2024

为了显示在小组件主机中，支持 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

图标

激活

CreateInstance

ActivateApplication

定义

功能

大小

ThemeResources

图标

屏幕截图

屏幕快照

DarkMode

图标

屏幕截图

屏幕快照

LightMode

图标

屏幕截图

屏幕快照

WidgetProvider

小组件提供程序注册信息的根元素。

WidgetProviderIcons

指定表示小组件提供程序应用的图标。

激活

指定小组件提供程序的激活信息。如果在清单中指定了 CreateInstance 和 ActivateApplication，则 CreateInstance 优先。

CreateInstance

应为实现 IWidgetProvider 接口的基于 Win32 的小组件提供程序指定 createInstance。系统将通过调用 CoCreateInstance 来激活接口。 ClassId 属性指定用于实现 IWidgetProvider 接口的 CreateInstance 服务器的 CLSID。

属性	类型	必需	说明	默认值
ClassId	GUID	是	用于实现小组件提供程序的 CreateInstance 服务器的 CLSID。	不可用

ActivateApplication

指定 ActivateApplication 时，小组件提供程序将通过命令行激活，参数提供为 base64url 编码 JSON 字符串。建议小组件提供程序使用 CreateInstance 激活类型。有关 ActivateApplication 命令行格式的信息，请参阅小组件提供程序 ActivateApplication 协议。

定义

一个或多个小组件注册的容器元素。

定义

表示单个小组件的注册。

属性	类型	必需	说明	默认值
Id	string	是	标识小组件的 ID。此值也会显示在小组件选取器导航栏中。小组件提供程序实现使用此字符串来确定或指定要为每个操作引用哪些应用的小组件。对于应用清单文件中定义的所有小组件，此字符串必须是唯一的。	不可用
DisplayName	string	是	小组件主机上显示的小组件的名称。	不可用
描述	字符串	是	小组件的简短说明。	不可用
AllowMultiple	boolean	否	如果仅支持此小组件的一个实例，则设置为 false。此属性是可选的，默认值为 true。	是
IsCustomizable	boolean	否	在 Windows App SDK 1.4 中引入。如果应用支持小组件自定义，则设置为 true。这会导致自定义小组件按钮显示在小组件的省略号菜单中。	false
AdditionalInfoUri	string	否	一个 URI，它可以与小组件相关联，当用户单击小组件框架的标题栏或单击其上下文菜单的 Powered by 元素时要使用的 URI。	空值
ExcludedRegions	string	否	小组件不应可用的区域列表。小组件可以指定 ExcludedRegions 或 ExclusiveRegions，但不能在单个小组件定义中同时指定这两者。该属性的值是两个字符区域代码的逗号分隔列表。	空值
ExclusiveRegions	string	否	应提供小组件的唯一区域的列表。小组件可以指定 ExcludedRegions 或 ExclusiveRegions，但不能在单个小组件定义中同时指定这两者。该属性的值是两个字符区域代码的逗号分隔列表。	空值

功能

可选。指定单个小组件的功能。如果未声明任何功能，则默认添加一个指定大小为“大”的功能。

功能

指定小组件的功能。

大小

指定关联的小组件支持的大小。

属性	类型	必需	说明	默认值
Name	字符串	是	指定小组件支持的大小。该值必须为下列值之一：“small”、“medium”、“large”	不可用

ThemeResources

指定小组件的主题资源。

图标

一个或多个 Icon 元素的容器元素。

图标

必需。指定在小组件的属性区域中显示的图标。

属性	类型	必需	说明	默认值
Path	string	是	图标图像文件的包相对路径。	不可用

屏幕截图

必需。指定小组件的一个或多个屏幕截图。

屏幕快照

必需。指定小组件的屏幕截图。当用户选择要添加到小组件主机的小组件时，“添加小组件”对话框会显示此屏幕截图。如果为下面列出的可选 DarkMode 或 LightMode 元素提供屏幕截图，则小组件主机将使用与当前设备主题匹配的屏幕截图。如果未提供当前设备主题的屏幕截图，将使用此“屏幕截图”元素中提供的图像。有关屏幕截图图像的设计要求和本地化屏幕截图的命名约定的信息，请参阅与小组件选取器集成。

注意

小组件屏幕截图不会显示在小组件板的“添加小组件”对话框的当前预览版本中。

属性	类型	必需	说明	默认值
Path	string	是	屏幕截图图像文件的包相对路径。	不可用
DisplayAltText	string	否	图像的替换文字，用于辅助功能。	不可用

DarkMode

可选。指定在设备上激活深色模式时的主题资源。如果在可选 DarkMode 元素中指定一个或多个屏幕截图图像，则当设备处于深色模式时，小组件主机将选择这些屏幕截图。如果未提供深色模式图像，小组件主机将使用上述所需顶级 屏幕截图 元素。有关屏幕截图图像的设计要求和本地化屏幕截图的命名约定的信息，请参阅与小组件选取器集成。

LightMode

可选。指定在设备上激活浅色模式时的主题资源。如果在可选 LightMode 元素中提供一个或多个屏幕截图图像，则当设备处于浅色模式时，小组件主机将选择这些屏幕截图。如果未提供浅色模式图像，小组件主机将使用上述所需顶级 屏幕截图 元素。有关屏幕截图图像的设计要求和本地化屏幕截图的命名约定的信息，请参阅与小组件选取器集成。

示例

以下代码示例演示了小组件包清单 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>

通过

应用扩展

元素层次结构

WidgetProvider

WidgetProviderIcons

激活

CreateInstance

ActivateApplication

定义

定义

功能

功能

大小

ThemeResources

图标

图标

屏幕截图

屏幕快照

DarkMode

LightMode

示例

其他资源