Creare un modello di widget con Progettazione delle schede adattive

L'interfaccia utente e l'interazione per i widget di Windows vengono implementati tramite schede adattive. Ogni widget fornisce un modello visivo e, facoltativamente, un modello di dati definito usando documenti JSON conformi allo schema delle 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 l'associazione dati 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 delle schede adattive

Progettazione delle schede adattive è uno strumento interattivo online che semplifica la generazione di modelli JSON per le 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, nell'elenco a discesa Seleziona app host, scegliere Scheda 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. Quello chiamato editor payload con etichetta contiene la definizione JSON dell'interfaccia utente 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 sull'associazione dati nelle schede adattive, vedere Linguaggio del modello delle schede adattive.

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, ad esempio la scheda Widget, hanno due proprietà che indicano le dimensioni e il tema del widget. Queste proprietà sono denominate host.widgetSize e host.hostTheme. Le dimensioni supportate sono "piccola", "media" e "grande". I temi supportati sono "chiaro" e "scuro". Il modello di widget può visualizzare in modo dinamico contenuti diversi in base al valore corrente di queste proprietà. Per vedere come il tuo widget risponde alle modifiche delle dimensioni e del tema, puoi regolare i valori di queste proprietà nell'editor, oppure puoi anche impostare questi valori nei menu a discesa Dimensioni container e Tema accanto al menu a discesa Seleziona app host in alto nella pagina.

Crea 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 esterni ai bordi del widget, ma verrà risolto nei passaggi seguenti.

Implementare il layout condizionale

L'editor payload scheda è stato aggiornato per riflettere gli elementi TextBlock che abbiamo aggiunto. Sostituisci la stringa JSON per l'oggetto body con la seguente:

"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\"}"
    }
]

Nel linguaggio del modello schede adattive, 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 proprietà $host.widgetSize. Per altre informazioni sulle condizioni supportate nelle schede adattive, vedere Layout condizionale con $when.

Ora l'anteprima dovrebbe apparire come la seguente immagine:

Si noti che le istruzioni condizionali non vengono riflesse 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 notare che l'anteprima passa per visualizzare solo textBlock per le dimensioni medie. 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.

Eseguire l'associazione al contesto 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 alla variabile $count. 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 influisce 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 in Progettazione schede adattive, ma è comunque possibile usare la finestra di progettazione per modificare il layout del pulsante all'interno dell'interfaccia utente.

Con le schede adattive, gli elementi interattivi vengono definiti con gli elementi azione. Aggiungere il blocco JSON seguente direttamente dopo l'elemento body nell'editor del payload della scheda. Assicurarsi di aggiungere una virgola dopo la parentesi chiusa (]) dell'elemento del corpo o la finestra di progettazione segnala 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à verb è 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.

Il modello completo di widget

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"
    }
  ]
}