小工具提供者封裝資訊清單 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

Icon

啟用

CreateInstance

ActivateApplication

定義

Capabilities

功能

大小

ThemeResources

圖示

Icon

螢幕擷取畫面

Screenshot

DarkMode

圖示

Icon

螢幕擷取畫面

Screenshot

LightMode

圖示

Icon

螢幕擷取畫面

Screenshot

WidgetProvider

小工具提供者註冊資訊的根元素。

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>

共用方式為

應用程式延伸模組

元素階層

WidgetProvider

WidgetProviderIcons

啟用

CreateInstance

ActivateApplication

定義

定義

Capabilities

功能

大小

ThemeResources

圖示

Icon

螢幕擷取畫面

Screenshot

DarkMode

LightMode

範例

其他資源