Formát XML manifestu balíčku zprostředkovatele widgetu

Aby bylo možné je zobrazit v hostiteli widgetů, musí aplikace, které podporují Windows widgety, zaregistrovat poskytovatele widgetů v systému. U aplikací Win32 se v současné době podporují jenom zabalené aplikace a poskytovatelé widgetů určují informace o registraci v souboru manifestu balíčku aplikace. Tento článek dokumentuje formát XML pro registraci widgetu. V části Příklad najdete výpis kódu ukázkového manifestu balíčku pro poskytovatele widgetu Win32.

Rozšíření aplikace

Soubor manifestu balíčku aplikace podporuje mnoho různých rozšíření a funkcí pro aplikace pro Windows. Formát manifestu balíčku aplikace je definován sadou schémat, která jsou zdokumentována v odkazu na schéma manifestu balíčku . Poskytovatelé widgetů deklarují své registrační informace v rámci uap3:AppExtension. Atribut Název rozšíření musí být nastaven na "com.microsoft.windows.widgets".

Poskytovatelé widgetů by měli zahrnout uap3:Properties jako podřízený prvek elementu uap3:AppExtension. Schéma manifestu balíčku nevynucuje strukturu prvku uap3:Properties jinak než vyžadováním dobře formátovaného XML. Zbytek tohoto článku popisuje formát XML, který hostitel widgetu očekává, aby úspěšně zaregistroval poskytovatele widgetu.

<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>

Hierarchie elementů

WidgetProvider

  ProviderIcons

    Icon

  Activation

    VytvořitInstanci

    Aktivovat aplikaci

  Definitions

    Definition

      Capabilities

        Schopnosti

          Velikost

      ThemeResources

        Icons

          Icon

        Snímky obrazovky

          Screenshot

        Tmavý režim

          Icons

            Icon

          Snímky obrazovky

            Screenshot

        Světlý režim

          Icons

            Icon

          Snímky obrazovky

            Screenshot

WidgetProvider

Kořenový prvek informací o registraci zprostředkovatele widgetu.

Snímek obrazovky s dialogovým oknem Přidat widget na panelu Widgets Zobrazuje dva sloupce položek, z nichž každý má ikonu a název aplikace a znaménko plus označující, že widget lze přidat.

WidgetProviderIcons

Určuje ikony představující aplikaci poskytovatele widgetu.

Activation

Určuje informace o aktivaci pro poskytovatele widgetu. Pokud jsou v manifestu zadány instance CreateInstance i ActivateApplication , má přednost instance CreateInstance .

VytvořitInstanci

Pro poskytovatele widgetů založených na Win32, kteří implementují rozhraní IWidgetProvider, by mělo být zadáno CreateInstance. Systém aktivuje rozhraní voláním CoCreateInstance. Atribut ClassId určuje CLSID pro createInstance server, který implementuje IWidgetProvider rozhraní.

Vlastnost Typ Required Description Výchozí hodnota
Classid GUID Ano CLSID pro server CreateInstance, který implementuje zprostředkovatele widgetu. N/A

Aktivovat aplikaci

Pokud je zadána funkce ActivateApplication , zprostředkovatel widgetu se aktivuje prostřednictvím příkazového řádku s argumenty zadanými jako řetězce JSON s kódováním base64url . Doporučujeme, aby poskytovatelé widgetů používali typ aktivace CreateInstance . Informace o formátu příkazového řádku ActivateApplication najdete v tématu Protokol ActivateApplication zprostředkovatele widgetu.

Definitions

Element kontejneru pro jednu nebo více registrací widgetů.

Definition

Představuje registraci pro jeden widget.

Vlastnost Typ Required Description Výchozí hodnota
Id řetězec Ano ID, které identifikuje widget. Tato hodnota se také zobrazí v navigačním panelu výběru widgetu. Implementace poskytovatele widgetů používají tento řetězec k určení nebo zadání, na který z widgetů aplikace se při jednotlivých operacích odkazuje. Tento řetězec musí být jedinečný pro všechny widgety definované v souboru manifestu aplikace. N/A
ZobrazovanýNázev řetězec Ano Název widgetu, který se zobrazí na hostiteli widgetů. N/A
Description řetězec Ano Stručný popis widgetu N/A
Allowmultiple Boolean Ne Pokud je podporována pouze jedna instance tohoto widgetu, nastavte hodnotu false. Tento atribut je nepovinný a výchozí hodnota je true. true
Je přizpůsobitelný Boolean Ne Představeno v Windows App SDK 1.4. Pokud vaše aplikace podporuje přizpůsobení widgetu, nastavte hodnotu true. To způsobí, že se tlačítko Přizpůsobit widget zobrazí v nabídce se třemi tečky widgetu. false
AdditionalInfoUri řetězec Ne Identifikátor URI, který lze přidružit k widgetu, který se má použít, když uživatel klikne na záhlaví rámečku widgetu nebo při kliknutí na prvek Powered by v jeho místní nabídce. N/A
Vyloučené oblasti řetězec Ne Seznam oblastí, kde by widget neměl být k dispozici. Widgety mohou určovat Vyloučené oblasti nebo ExclusiveRegions , ale nesmí být zadány v jedné definici widgetu. Hodnota atributu je čárkami oddělený seznam dvou znakových kódů oblastí. N/A
ExclusiveRegions řetězec Ne Seznam jediných oblastí, ve kterých by měl být widget dostupný. Widgety mohou určovat Vyloučené oblasti nebo ExclusiveRegions , ale nesmí být zadány v jedné definici widgetu. Hodnota atributu je čárkami oddělený seznam dvou znakových kódů oblastí. N/A
WebRequestFilter řetězec Ne Určuje filtr, který určuje adresy URL požadavků na prostředky, pro které se požadavek zachytí a přesměruje na implementaci poskytovatele widgetu IWidgetResourceProvider.OnResourceRequested. Vzor filtru se vyjadřuje pomocí formátu popsaného ve vzorech shody. V případě potřeby musí řetězec filtru v registraci používat punycode . Řetězec filtru musí odpovídat původu registrace widgetu, který je zadaný v poli webUrl obsahu adaptivní karty. N/A

Capabilities

Optional. Určuje možnosti pro jeden widget. Pokud nejsou deklarovány žádné možnosti, jedna možnost určující "velkou" velikost se ve výchozím nastavení přidá.

Schopnosti

Určuje schopnost widgetu.

Velikost

Určuje podporované velikosti přidruženého widgetu.

Vlastnost Typ Required Description Výchozí hodnota
Name řetězec Ano Určuje podporovanou velikost widgetu. Hodnota musí být jedna z následujících hodnot: "small", "medium", "large" N/A

ThemeResources

Určuje prostředky motivu pro widget.

Icons

Element kontejneru pro jeden nebo více prvků Icon .

Icon

Required. Určuje ikonu, která se zobrazí v oblasti přisuzování widgetu.

Vlastnost Typ Required Description Výchozí hodnota
Path řetězec Ano Relativní cesta k souboru s obrázkem ikony v balíčku. N/A

Snímky obrazovky

Required. Určuje jeden nebo více snímků obrazovky widgetu.

Screenshot

Required. Určuje snímek obrazovky widgetu. Tento snímek obrazovky se zobrazuje v hostiteli widgetů v dialogovém okně Přidat widgety , když uživatel vybírá widgety pro přidání do hostitele widgetů. Pokud zadáte snímek obrazovky pro volitelné prvky DarkMode nebo LightMode uvedené níže, hostitel widgetů použije snímek obrazovky, který odpovídá aktuálnímu motivu zařízení. Pokud nezadáte snímek obrazovky pro aktuální motiv zařízení, použije se obrázek uvedený v tomto prvku snímku obrazovky . Informace o požadavcích na návrh obrázků snímků obrazovky a konvencích vytváření názvů pro lokalizované snímky obrazovky najdete v tématu Integrace s nástrojem pro výběr widgetu.

Vlastnost Typ Required Description Výchozí hodnota
Path řetězec Ano Relativní cesta v rámci balíčku k souboru s obrázkem snímku obrazovky. N/A
DisplayAltText řetězec Ne Alternativní text obrázku pro usnadnění přístupu. N/A

Tmavý režim

Optional. Určuje prostředky motivu, když je v zařízení aktivní tmavý režim. Pokud zadáte jeden nebo více obrázků snímku obrazovky v volitelném prvku DarkMode , hostitel widgetů vybere tyto snímky obrazovky, když je zařízení v tmavém režimu. Pokud nezadáte tmavý režim obrázku, hostitel widgetů použije požadovaný prvek snímku obrazovky nejvyšší úrovně popsaný výše. Informace o požadavcích na návrh obrázků snímků obrazovky a konvencích vytváření názvů pro lokalizované snímky obrazovky najdete v tématu Integrace s nástrojem pro výběr widgetu.

Světlý režim

Optional. Určuje prostředky motivu pro případ, kdy je na zařízení aktivní světlý režim. Pokud do volitelného prvku LightMode zadáte jeden nebo více obrázků snímku obrazovky, hostitel widgetů vybere tyto snímky obrazovky, když je zařízení v režimu světla. Pokud nezadáte obrázek světlého režimu, hostitel widgetů použije požadovaný prvek snímku obrazovky nejvyšší úrovně popsaný výše. Informace o požadavcích na návrh obrázků snímků obrazovky a konvencích vytváření názvů pro lokalizované snímky obrazovky najdete v tématu Integrace s nástrojem pro výběr widgetu.

Example

Následující příklad kódu znázorňuje použití formátu XML manifestu balíčku widgetu.

<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>
  • Last updated on