Condividi tramite

Formato XML del manifesto del pacchetto del provider widget

  • Articolo

Per essere visualizzati nell'host dei widget, le app che supportano i widget di Windows devono registrare il provider di widget con il sistema. Per le app Win32, solo le app in pacchetto attualmente sono supportate e i provider di widget specificano le informazioni di registrazione nel file manifesto del pacchetto dell'app. Questo articolo illustra il formato XML per la registrazione di widget. Vedere la sezione Esempio per un elenco di codice di un manifesto del pacchetto di esempio per un provider di widget Win32.

Estensione di app

Il file manifesto del pacchetto dell'app supporta molte estensioni e funzionalità diverse per le app di Windows. Il formato manifesto del pacchetto dell'app è definito da un set di schemi documentati nel Riferimento dello schema del manifesto del pacchetto. I widget di ricerca dichiarano le informazioni di registrazione all'interno di uap3:AppExtension. L'attributo Name dell'estensione deve essere impostato su "com.microsoft.windows.widgets".

I provider di widget devono includere uap3:Properties come figlio di uap3:AppExtension. Lo schema del manifesto del pacchetto non applica la struttura dell'elemento uap3:Properties diverso dalla richiesta di XML ben corretto. Nella parte restante di questo articolo viene descritto il formato XML previsto dall'host di widget per registrare correttamente un provider di widget.

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

Gerarchia elementi

WidgetProvider

  ProviderIcons

    Icon

  Attivazione

    CreateInstance

    ActivateApplication

  Definizioni

    Definizione

      Funzionalità

        Funzionalità

          Dimensione

      ThemeResources

        Icone

          Icon

        Screenshot

          Schermata

        DarkMode

          Icone

            Icon

          Screenshot

            Schermata

        LightMode

          Icone

            Icon

          Screenshot

            Schermata

WidgetProvider

Elemento radice delle informazioni di registrazione del provider di widget.

Screenshot della finestra di dialogo Aggiungi widget nella scheda Widget. Mostra due colonne di voci, ognuna con un'icona e un nome dell'app, con un segno più che indica che un widget può essere aggiunto

WidgetProviderIcons

Specifica le icone che rappresentano l'app del provider di widget.

Attivazione

Specifica le informazioni di attivazione per il provider di widget. Se CreateInstance e ActivateApplication vengono specificati nel manifesto, CreateInstance ha la precedenza.

CreateInstance

È necessario specificare CreateInstance per i provider di widget basati su Win32 che implementano l'interfaccia IWidgetProvider. Il sistema attiverà l'interfaccia con una chiamata a CoCreateInstance. L'attributo ClassId specifica il CLSID per il server CreateInstance che implementa l'interfaccia IWidgetProvider.

Attributo Type Obbligatorio Descrizione Default value
ClassId GUID Sì CLSID per il server CreateInstance che implementa il provider di widget. N/D

ActivateApplication

Quando viene specificato ActivateApplication, il provider di widget viene attivato tramite la riga di comando, con gli argomenti forniti come stringhe JSON con codifica base64url. È consigliabile che i provider di widget usino il tipo di attivazione CreateInstance . Per informazioni sul formato della riga di comando ActivateApplication, consultare il protocollo ActivateApplication del provider widget.

Definizioni

Elemento contenitore per una o più registrazioni di widget.

Definizione

Rappresenta la registrazione per un singolo widget.

Attributo Type Obbligatorio Descrizione Default value
Id string Sì ID che identifica il widget. Questo valore viene visualizzato anche nella barra di spostamento della selezione widget. Le implementazioni del provider di widget usano questa stringa per determinare o specificare a quale widget dell'app viene fatto riferimento per ogni operazione. Questa stringa deve essere univoca per tutti i widget definiti all'interno del file manifesto dell'app. N/D
DisplayName string Sì Nome del widget visualizzato nell'host dei widget. N/D
Descrizione string Sì Breve descrizione dello widget. N/D
AllowMultiple boolean No Impostare su false se è supportata una sola istanza di questo widget. Questo attributo è facoltativo e il valore predefinito è true. true
IsCustomizable boolean No Introdotto in Windows App SDK 1.4. Impostare su true se l'app supporta la personalizzazione dei widget. In questo modo il pulsante Personalizza widget viene visualizzato nel menu con i puntini di sospensione del widget. false
AdditionalInfoUri string No URI che può essere associato al widget da usare quando l'utente fa clic sulla barra del titolo del frame del widget o quando si fa clic sull'elemento Powered by del relativo menu di scelta rapida. N/D
ExcludedRegions string No Elenco di aree in cui il widget non deve essere disponibile. I widget possono specificare ExcludedRegions o ExclusiveRegions, ma non devono specificare entrambi in una singola definizione di widget. Il valore dell'attributo è un elenco delimitato da virgole di due codici di area di caratteri. N/D
ExclusiveRegions string No Elenco delle uniche aree in cui deve essere disponibile il widget. I widget possono specificare ExcludedRegions o ExclusiveRegions, ma non devono specificare entrambi in una singola definizione di widget. Il valore dell'attributo è un elenco delimitato da virgole di due codici di area di caratteri. N/D
WebRequestFilter string No Specifica il filtro che specifica gli URL della richiesta di risorsa per i quali la richiesta verrà intercettata e reindirizzata all'implementazione del provider di widget di IWidgetResourceProvider.OnResourceRequested. Il schema di filtro viene espresso utilizzando il formato descritto in modelli di corrispondenza. La stringa di filtro nella registrazione deve usare Punycode laddove necessario. La stringa di filtro deve corrispondere all'origine della registrazione del widget, specificata nel campo webUrl del contenuto della scheda adattiva. N/D

Funzionalità

Facoltativo. Specifica le funzionalità per un singolo widget. Se non vengono dichiarate funzionalità, per impostazione predefinita viene aggiunta una funzionalità che specifica una dimensione "large".

Funzionalità

Specifica una funzionalità per un widget.

Dimensione

Specifica le dimensioni supportate per il widget associato.

Attributo Type Obbligatorio Descrizione Default value
Nome string Sì Specifica una dimensione supportata per un widget. Il valore deve essere uno dei seguenti: "small", "medium", "large" N/D

ThemeResources

Specifica le risorse del tema per un widget.

Icone

Elemento contenitore per uno o più elementi Icona.

Icon

Obbligatorio. Specifica un'icona visualizzata nell'area di attribuzione del widget.

Attributo Type Obbligatorio Descrizione Default value
Percorso string Sì Percorso relativo al pacchetto di un file di immagine icona. N/D

Screenshot

Obbligatorio. Specifica uno o più screenshot del widget.

Schermata

Obbligatorio. Specifica uno screenshot per un widget. Questo screenshot viene visualizzato nell'host dei widget nella finestra di dialogo Aggiungi Widget quando l'utente seleziona i widget da aggiungere all'host dei widget. Se si fornisce uno screenshot per gli elementi facoltativi DarkMode o LightMode elencati di seguito, quindi l'host dei widget utilizzerà lo screenshot che corrisponde al tema del dispositivo corrente. Se non si fornisce uno screenshot per il tema del dispositivo corrente, verrà usata l'immagine fornita in questo elemento Screenshot. Per informazioni sui requisiti di progettazione per le immagini di screenshot e sulle convenzioni di denominazione per gli screenshot localizzati, vedere Integrare con la selezione widget.

Nota

Gli screenshot del widget non vengono visualizzati nella finestra di dialogo Aggiungi widget della scheda widget nella versione di anteprima corrente.

Attributo Type Obbligatorio Descrizione Default value
Percorso string Sì Percorso relativo al pacchetto di un file di immagine screenshot. N/D
DisplayAltText string No Testo alternativo per l'immagine, per l'accessibilità. N/D

DarkMode

Facoltativo. Specifica le risorse del tema in caso la modalità scura è attiva nel dispositivo. Se si specifica una o più immagini di screenshot nell'elemento facoltativo DarkMode, l'host widget selezionerà questi screenshot quando il dispositivo è in modalità scura. Se non si fornisce un'immagine in modalità scura, l'host dei widget userà l'elemento Screenshot di primo livello richiesto descritto in precedenza. Per informazioni sui requisiti di progettazione per le immagini di screenshot e sulle convenzioni di denominazione per gli screenshot localizzati, vedere Integrare con la selezione widget.

LightMode

Facoltativo. Specifica le risorse del tema in caso la modalità chiara è attiva nel dispositivo. Se si fornisce una o più immagini di screenshot nell'elemento facoltativo LightMode, l'host widget selezionerà questi screenshot quando il dispositivo è in modalità chiara. Se non si fornisce un'immagine in modalità chiara, l'host dei widget userà l'elemento Screenshot di primo livello richiesto descritto in precedenza. Per informazioni sui requisiti di progettazione per le immagini di screenshot e sulle convenzioni di denominazione per gli screenshot localizzati, vedere Integrare con la selezione widget.

Esempio

Nell'esempio di codice seguente viene illustrato l'utilizzo del formato XML del manifesto del pacchetto del widget.

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