Format XML manifestu pakietu dostawcy widżetu

Aby można je było wyświetlić na hoście widżetów, aplikacje obsługujące widżety Windows muszą zarejestrować dostawcę widżetów w systemie. W przypadku aplikacji Win32 obecnie obsługiwane są tylko spakowane aplikacje, a dostawcy widżetów określają informacje o rejestracji w pliku manifestu pakietu aplikacji. W tym artykule opisano format XML służący do rejestracji widżetu. Zobacz sekcję Przykład , aby zapoznać się z listą kodu przykładowego manifestu pakietu dla dostawcy widżetu Win32.

Rozszerzenie aplikacji

Plik manifestu pakietu aplikacji obsługuje wiele różnych rozszerzeń i funkcji dla aplikacji systemu Windows. Format manifestu pakietu aplikacji jest określany przez zestaw schematów, które są udokumentowane w odwołaniu do schematu manifestu pakietu . Dostawcy widżetów deklarują informacje o rejestracji w elemencie uap3:AppExtension. Atrybut Name rozszerzenia musi być ustawiony na "com.microsoft.windows.widgets".

Dostawcy widżetów powinni uwzględnić właściwości uap3:Properties jako element podrzędny uap3:AppExtension. Schemat manifestu pakietu nie wymusza struktury elementu uap3:Properties innego niż wymaganie poprawnie sformułowanego kodu XML. W pozostałej części tego artykułu opisano format XML oczekiwany przez hosta widżetu w celu pomyślnego zarejestrowania dostawcy widżetu.

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

Hierarchia elementów

WidgetProvider

  ProviderIcons

    Icon

  Activation

    CreateInstance

    Aktywowanie aplikacji

  Definitions

    Definition

      Możliwości

        Capability

          Size

      ThemeResources

        Icons

          Icon

        Zrzuty ekranu

          Screenshot

        DarkMode

          Icons

            Icon

          Zrzuty ekranu

            Screenshot

        LightMode

          Icons

            Icon

          Zrzuty ekranu

            Screenshot

WidgetProvider

Główny element informacji o rejestracji dostawcy widżetów.

WidgetProviderIcons

Określa ikony reprezentujące aplikację dostawcy widżetów.

Activation

Określa informacje o aktywacji dostawcy widżetu. Jeśli w manifeście określono zarówno CreateInstance, jak i ActivateApplication, pierwszeństwo ma CreateInstance.

CreateInstance

CreateInstance należy określić dla dostawców widżetów opartych na technologii Win32, którzy implementują interfejs IWidgetProvider. System aktywuje interfejs za pomocą wywołania metody CoCreateInstance. Atrybut ClassId określa CLSID dla serwera CreateInstance, który implementuje interfejs IWidgetProvider .

Attribute	Typ	Required	Opis	Wartość domyślna
Classid	GUID	Yes	Identyfikator CLSID serwera CreateInstance, który implementuje dostawcę widżetu.	N/A

Aktywowanie aplikacji

Po określeniu parametru ActivateApplication dostawca widżetu jest aktywowany za pośrednictwem wiersza polecenia z argumentami podanymi jako ciągi JSON zakodowane w formacie base64url . Zaleca się, aby dostawcy widżetów używali typu aktywacji CreateInstance . Aby uzyskać informacje na temat formatu wiersza polecenia ActivateApplication , zobacz Widget provider ActivateApplication protocol (Aktywowanie protokołu ActivateApplication dostawcy widżetów).

Definitions

Element kontenera dla jednej lub większej liczby rejestracji widżetów.

Definition

Reprezentuje rejestrację pojedynczego widżetu.

Attribute	Typ	Required	Opis	Wartość domyślna
Id	ciąg	Yes	Identyfikator identyfikujący widżet. Ta wartość jest również wyświetlana na pasku nawigacyjnym selektora widżetów. Implementacje dostawcy widżetów używają tego ciągu, aby ustalić lub określić, do którego widżetu aplikacji następuje odwołanie w ramach każdej operacji. Ten ciąg musi być unikatowy dla wszystkich widżetów zdefiniowanych w pliku manifestu aplikacji.	N/A
DisplayName	ciąg	Yes	Nazwa widżetu wyświetlanego na hoście widżetów.	N/A
Opis	ciąg	Yes	Krótki opis widżetu.	N/A
Allowmultiple	boolean	No	Ustaw wartość false, jeśli obsługiwane jest tylko jedno wystąpienie tego widżetu. Ten atrybut jest opcjonalny, a wartość domyślna to true.	prawda
Jestkonfigurowalny	boolean	No	Wprowadzono w wersji Zestaw SDK do aplikacji systemu Windows 1.4. Ustaw wartość true, jeśli aplikacja obsługuje dostosowywanie widżetu. Spowoduje to wyświetlenie przycisku Dostosuj widżet w menu wielokropka widżetu.	fałszywy
AdditionalInfoUri	ciąg	No	Adres URI, który można skojarzyć z widżetem i używać po kliknięciu paska tytułu ramki widżetu lub elementu Obsługiwane przez w jego menu kontekstowym.	N/A
Wykluczoneregiony	ciąg	No	Lista regionów, w których widżet nie powinien być dostępny. Widżety mogą określać wykluczoneregiony lub ekskluzywneRegiony , ale nie mogą określać obu elementów w jednej definicji widżetu. Wartość atrybutu to rozdzielona przecinkami lista dwóch kodów regionów znaków.	N/A
Ekskluzywneregiony	ciąg	No	Lista jedynych regionów, w których widżet powinien być dostępny. Widżety mogą określać ExcludedRegions lub ExclusiveRegions, ale nie mogą określać obu tych elementów w definicji jednego widżetu. Wartość atrybutu to rozdzielona przecinkami lista dwóch kodów regionów znaków.	N/A
WebRequestFilter	ciąg	No	Określa filtr określający adresy URL żądania zasobu, dla których żądanie zostanie przechwycone i przekierowane do implementacji dostawcy widżetu IWidgetResourceProvider.OnResourceRequested. Wzorzec filtru jest wyrażany przy użyciu formatu opisanego w Match Patterns. W razie potrzeby w rejestracji ciąg filtru musi używać Punycode. Ciąg filtru musi odpowiadać źródłu rejestracji widżetu, określonemu w polu webUrl w treści karty adaptacyjnej.	N/A

Możliwości

Optional. Określa możliwości pojedynczego widżetu. Jeśli nie zadeklarowane są żadne możliwości, domyślnie jest dodawana jedna możliwość określająca "duży" rozmiar.

Capability

Określa funkcję widżetu.

Size

Określa obsługiwane rozmiary skojarzonego widżetu.

Attribute	Typ	Required	Opis	Wartość domyślna
Nazwa	ciąg	Yes	Określa obsługiwany rozmiar widżetu. Wartość musi być jedną z następujących wartości: "small", "medium", "large"	N/A

ThemeResources

Określa zasoby motywu dla widżetu.

Icons

Element kontenera dla co najmniej jednego elementu Ikona .

Icon

Required. Określa ikonę wyświetlaną w obszarze przypisywania widżetu.

Attribute	Typ	Required	Opis	Wartość domyślna
Path	ciąg	Yes	Ścieżka względna pakietu do pliku obrazu ikony.	N/A

Zrzuty ekranu

Required. Określa co najmniej jeden zrzut ekranu widżetu.

Screenshot

Required. Określa zrzut ekranu widżetu. Ten zrzut ekranu jest wyświetlany na hoście widżetów w oknie dialogowym Dodawanie widżetów , gdy użytkownik wybiera widżety do dodania do hosta widżetów. Jeśli udostępnisz zrzut ekranu dla opcjonalnych elementów DarkMode lub LightMode wymienionych poniżej, host widżetów użyje zrzutu ekranu pasujący do bieżącego motywu urządzenia. Jeśli nie udostępnisz zrzutu ekranu bieżącego motywu urządzenia, zostanie użyty obraz przedstawiony w tym elemencie Zrzut ekranu . Aby uzyskać informacje o wymaganiach projektowych dotyczących obrazów zrzutów ekranu i konwencji nazewnictwa zlokalizowanych zrzutów ekranu, zobacz Integrowanie z selektorem widżetów.

Attribute	Typ	Required	Opis	Wartość domyślna
Path	ciąg	Yes	Ścieżka względna pakietu do pliku obrazu zrzutu ekranu.	N/A
DisplayAltText	ciąg	No	Tekst alternatywny dla obrazu w celu ułatwienia dostępu.	N/A

DarkMode

Optional. Określa zasoby motywu, gdy na urządzeniu jest aktywny tryb ciemny. Jeśli określisz co najmniej jeden obraz zrzutu ekranu w opcjonalnym elemecie DarkMode , host widżetów wybierze te zrzuty ekranu, gdy urządzenie jest w trybie ciemnym. Jeśli nie podasz obrazu trybu ciemnego, host widżetów będzie używać wymaganego elementu zrzutu ekranu najwyższego poziomu opisanego powyżej. Aby uzyskać informacje o wymaganiach projektowych dotyczących obrazów zrzutów ekranu i konwencji nazewnictwa zlokalizowanych zrzutów ekranu, zobacz Integrowanie z selektorem widżetów.

LightMode

Optional. Określa zasoby motywu używane, gdy na urządzeniu jest aktywny tryb jasny. Jeśli udostępnisz co najmniej jeden obraz zrzutu ekranu w opcjonalnym elemecie LightMode , host widżetów wybierze te zrzuty ekranu, gdy urządzenie jest w trybie świetlnym. Jeśli nie udostępnisz obrazu trybu światła, host widżetów będzie używać wymaganego elementu zrzutu ekranu najwyższego poziomu opisanego powyżej. Aby uzyskać informacje o wymaganiach projektowych dotyczących obrazów zrzutów ekranu i konwencji nazewnictwa zlokalizowanych zrzutów ekranu, zobacz Integrowanie z selektorem widżetów.

Example

Poniższy przykład kodu ilustruje użycie formatu XML manifestu pakietu widżetu.

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