Creare un modello di widget con Schede adattive Designer

Annotazioni

Alcune informazioni sono relative a un prodotto non definitivo, che potrebbe subire modifiche sostanziali prima del rilascio sul mercato. Microsoft non fornisce alcuna garanzia, espressa o implicita, rispetto alle informazioni fornite qui.

Importante

La funzionalità descritta in questo argomento è disponibile nelle build di anteprima di Dev Channel di Windows a partire dalla build 25217. Per informazioni sulle build di anteprima di Windows, vedere Windows 10 Insider Preview.

L'interfaccia utente e l'interazione per i widget di Windows vengono implementati usando Schede adattive. Ogni widget fornisce un modello visivo e, facoltativamente, un modello di dati definito usando documenti JSON conformi allo schema Schede adattive. Questo articolo illustra i passaggi per creare un modello di widget semplice.

Widget di conteggio

L'esempio in questo articolo è un semplice widget di conteggio che visualizza un valore intero e consente all'utente di incrementare il valore facendo clic su un pulsante nell'interfaccia utente del widget. Questo modello di esempio usa il data binding per aggiornare automaticamente l'interfaccia utente in base al contesto dati.

Le app devono implementare un provider di widget per generare e aggiornare il modello di widget e/o i dati e passarli all'host del widget. L'articolo Implementare un provider di widget in un'app win32 fornisce indicazioni dettagliate per implementare il provider di widget per il widget di conteggio che verrà generato nei passaggi seguenti.

Progettazione Schede adattive

Schede adattive Designer è uno strumento interattivo online che semplifica la generazione di modelli JSON per Schede adattive. Usando la finestra di progettazione, è possibile visualizzare gli oggetti visivi sottoposti a rendering e il comportamento del data binding in tempo reale durante la compilazione del modello di widget. Seguire il collegamento per aprire la finestra di progettazione, che verrà usata per tutti i passaggi di questa procedura dettagliata.

Creare un modello vuoto da un set di impostazioni

Nella parte superiore della pagina, dal menu a discesa Seleziona app host scegliere Bacheca widget. In questo modo verranno impostate le dimensioni del contenitore per la scheda adattiva in modo da avere una dimensione supportata per i widget. Si noti che i widget supportano dimensioni piccole, medie e grandi. Le dimensioni del set di impostazioni del modello predefinito sono le dimensioni corrette per un widget di piccole dimensioni. Non preoccuparti se il contenuto supera i bordi perché lo sostituiamo con il contenuto progettato per adattarsi all'interno del widget.

Nella parte inferiore della pagina sono disponibili tre editor di testo. L'editor Editor del Payload della Scheda contiene la definizione JSON dell'UI del widget. L'editor con etichetta Sample Data Editor contiene JSON che definisce un contesto dati facoltativo per il widget. Il contesto dei dati viene associato dinamicamente alla scheda adattiva quando viene eseguito il rendering del widget. Per altre informazioni sul data binding in Schede adattive, vedere Schede adattive Template Language.

Il terzo editor di testo è etichettato Sample Host Data Editor. Si noti che questo editor può essere compresso sotto gli altri due editor della pagina. In tal caso, fare clic su + per espandere l'editor. Le app host widget possono specificare le proprietà host che è possibile usare nel modello di widget per visualizzare in modo dinamico contenuto diverso in base ai valori delle proprietà correnti. La scheda Widgets supporta le proprietà host seguenti.

Proprietà	Valore	Descrizione
host.widgetSize	"piccolo", "medio" o "grande"	Dimensioni del widget aggiunto.
host.hostTheme	"chiaro" o "scuro"	Tema corrente del dispositivo in cui viene visualizzata la scheda Widget.
host.isSettingsPayload	vero o falso	Quando questo valore è true, l'utente ha fatto clic sul pulsante Personalizza widget nel menu di scelta rapida del widget. È possibile usare questo valore della proprietà per visualizzare gli elementi dell'interfaccia utente delle impostazioni di personalizzazione. Si tratta di un metodo alternativo all'uso di IWidgetProvider2.OnCustomizationRequested per modificare il payload JSON nell'app del provider di widget. Per altre informazioni, vedere Implementazione della personalizzazione dei widget.
host.isHeaderSupported	vero o falso	Se questo valore è true, la personalizzazione dell'intestazione è supportata. Per altre informazioni, vedere isHeaderSupported.
host.isHeader	vero o falso	Quando questo valore è true, l'host richiede un payload specificamente per il rendering dell'intestazione del widget.
host.isWebSupported	vero o falso	Quando questo valore è false, l'host non supporta attualmente il caricamento del contenuto Web di un widget. In questo caso, i widget Web visualizzeranno il payload JSON di fallback fornito dal provider di widget, ma questo valore può essere usato per personalizzare ulteriormente il contenuto. Per altre informazioni, vedere Provider di widget Web
host.isUserContextAuthenticated	vero o falso	Quando questo valore è false, l'unica azione supportata è Action.OpenUrl. Il valore di isUserContextAuthenticated può essere usato per regolare il contenuto del widget in modo appropriato, in base alle limitazioni di interattività.

Gli elenchi a discesa Dimensioni contenitore e Tema accanto all'elenco a discesa Seleziona app host nella parte superiore della pagina consentono di impostare queste proprietà senza modificare manualmente il codice JSON host di esempio nell'editor.

Creare una nuova scheda

Nell'angolo superiore sinistro della pagina fare clic su Nuova scheda. Nella finestra di dialogo Crea selezionare Scheda vuota. Dovrebbe ora essere visualizzata una scheda adattiva vuota. Si noterà anche che il documento JSON nell'editor di dati di esempio è vuoto.

Il widget di conteggio che verrà creato è molto semplice, costituito solo da 4 elementi TextBlock e da un'azione di tipo Action.Execute, che definisce il pulsante del widget.

Aggiungere elementi TextBlock

Aggiungere quattro elementi TextBlock trascinandoli dal riquadro Elementi scheda a sinistra della pagina nella scheda adattiva vuota nel riquadro di anteprima. A questo punto, l'anteprima del widget dovrebbe essere simile all'immagine seguente. Il contenuto supera di nuovo i bordi del widget, ma verrà risolto nei seguenti passaggi.

Implementazione del layout condizionale

L'editor del payload della scheda è stato aggiornato per riflettere l'elemento TextBlock che abbiamo aggiunto. Sostituire la stringa JSON per l'oggetto corpo con quanto segue:

"body": [
    {
        "type": "TextBlock",
        "text": "You have clicked the button ${count} times"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if medium",
        "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if small",
        "$when": "${$host.widgetSize==\"small\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if large",
        "$when": "${$host.widgetSize==\"large\"}"
    }
]

Nella Schede adattive Template Language la proprietà $when specifica che l'elemento contenitore viene visualizzato quando il valore associato restituisce true. Se il valore restituisce false, l'elemento contenitore non viene visualizzato. Nell'elemento body dell'esempio verrà visualizzato uno dei tre elementi TextBlock e gli altri due nascosti, a seconda del valore della $host.widgetSize proprietà. Per altre informazioni sulle condizioni supportate in Schede adattive, vedere Layout condizionale con $when.

L'anteprima dovrebbe ora essere simile all'immagine seguente:

Si noti che le dichiarazioni condizionali non vengono visualizzate nell'anteprima. Ciò è dovuto al fatto che la finestra di progettazione non simula il comportamento dell'host widget. Fare clic sul pulsante Modalità di anteprima nella parte superiore della pagina per avviare la simulazione. L'anteprima del widget è ora simile all'immagine seguente:

Nell'elenco a discesa Dimensioni contenitore, selezionare "Medio" e si noti che l'anteprima passa per visualizzare solo il TextBlock per la dimensione media. Il contenitore nell'anteprima cambia anche le dimensioni, dimostrando come è possibile usare l'anteprima per assicurarsi che l'interfaccia utente si adatti al contenitore widget per ogni dimensione supportata.

Associare al contesto dei dati

Il widget di esempio userà una proprietà di stato personalizzata denominata "count". È possibile vedere nel modello corrente che il valore per il primo TextBlock include il riferimento $countalla variabile . Quando il widget è in esecuzione nella scheda Widget, il provider di widget è responsabile dell'assemblaggio del payload dei dati e del passaggio all'host del widget. In fase di progettazione, è possibile usare l'Editor di dati di esempio per creare un prototipo del payload dei dati e vedere in che modo i diversi valori influiscono sulla visualizzazione del widget. Sostituire il payload di dati vuoto con il codice JSON seguente.

{"count": "2"}

Si noti che l'anteprima inserisce ora il valore specificato per la proprietà count nel testo per il primo TextBlock.

Aggiungere un pulsante

Il passaggio successivo consiste nell'aggiungere un pulsante al widget. Nell'host del widget, quando l'utente fa clic sul pulsante, l'host effettuerà una richiesta al provider di widget. Per questo esempio, il provider di widget incrementerà il valore del conteggio e restituirà un payload di dati aggiornato. Poiché questa operazione richiede un provider di widget, non sarà possibile visualizzare questo comportamento nella finestra di progettazione Schede adattive, ma è comunque possibile usare la finestra di progettazione per modificare il layout del pulsante all'interno dell'interfaccia utente.

Con Schede adattive, gli elementi interattivi vengono definiti con elementi action. Aggiungere il blocco JSON seguente direttamente dopo l'elemento body nell'editor del payload della scheda. Assicurati di aggiungere una virgola dopo la parentesi chiusa (]) dell'elemento body o il designer segnalerà un errore di formattazione.

,
"actions": [                                                      
    {                                                               
        "type": "Action.Execute",                               
        "title": "Increment",                                   
        "verb": "inc"                                           
    }                                                               
]

In questa stringa JSON, la proprietà type specifica il tipo di azione rappresentato. I widget supportano solo il tipo di azione "Action.Execute". Il titolo contiene il testo visualizzato sul pulsante per l'azione. La proprietà verbo è una stringa definita dall'app che l'host del widget invierà al provider di widget per comunicare la finalità associata all'azione. Un widget può avere più azioni e il codice del provider di widget verificherà il valore del verbo nella richiesta per determinare l'azione da eseguire.

Modello di widget completo

L'elenco di codice seguente mostra la versione finale del payload JSON.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
    {
      "type": "TextBlock",
      "text": "You have clicked the button ${count} times"
    },
    {
      "type": "TextBlock",
       "text": "Rendering Only if Small",
      "$when": "${$host.widgetSize==\"small\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Medium",
      "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Large",
      "$when": "${$host.widgetSize==\"large\"}"
    }
    ],
   "actions": [
    {
      "type": "Action.Execute",
      "title": "Increment",
      "verb": "inc"
    }
  ]
}

Esempio di payload delle impostazioni

L'elenco di codice seguente mostra un semplice esempio di payload JSON che usa la proprietà host.isSettingsPayload per visualizzare contenuto diverso quando l'utente ha fatto clic sul pulsante Personalizza widget .

{
    "type": "AdaptiveCard",
    "body": [
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Content payload",
                "$when": "${!$host.isSettingsPayload}"
            }
        ]
    },
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Settings payload",
                "$when": "${$host.isSettingsPayload}"
            }
        ]
    }
],
"actions": [
    {
    "type": "Action.Submit",
    "title": "Increment",
    "verb": "inc",
    "$when": "${!$host.isSettingsPayload}"
    },
    {
    "type": "Action.Submit",
    "title": "Update Setting",
    "verb": "setting",
    "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}