Creare un modello di widget con Schede adattive Designer

Per un widget Adaptive Card, definire l'interfaccia utente e le interazioni con un modello JSON di Schede adattive e, facoltativamente, un payload di dati JSON separato. Questo articolo illustra un modello di widget per il conteggio con data binding e layout condizionale. I widget di Windows possono anche visualizzare HTML da un URL; per tale formato di contenuto, vedere Provider di widget Web.

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

Il Schede adattive Designer è uno strumento online per la modifica del codice JSON della scheda e l'anteprima del layout e del data binding. Aprire il Designer per lavorare sul modello.

Importante

Designer usa un proprio renderer e opzioni host dedicate. Non presupporre che le funzionalità offerte siano supportate dalla bacheca Widgets o che fornisca valori specifici di Windows $host. Questa procedura dettagliata non dipende da un set di impostazioni host o da un editor di dati host. Testare il modello finale in un provider di widget Windows per ogni dimensione e tema supportati.

Le immagini seguenti illustrano il layout della scheda, non l'interfaccia Designer corrente.

Iniziare con una scheda vuota

L'editor payload della scheda contiene la definizione JSON della scheda. Sostituire il suo contenuto con questa scheda vuota:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": []
}

L'editor di dati di esempio contiene un contesto dati JSON facoltativo. Per informazioni sull'associazione dei dati al modello, vedere Schede adattive Template Language.

Proprietà dell'host dei widget di Windows

La scheda Widgets fornisce le proprietà host in fase di esecuzione. Fai riferimento a essi tramite $host nelle espressioni di modello, ad esempio ${$host.widgetSize}. Queste proprietà sono separate dal payload dei dati del provider; l'aggiunta di un widgetSize campo ai dati di esempio non imposta $host.widgetSize.

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

Il widget di conteggio usa quattro elementi TextBlock e un'azione Action.Execute per il relativo pulsante.

Aggiungere elementi TextBlock

Aggiungere quattro elementi TextBlock dalla tavolozza degli elementi della finestra di progettazione o aggiungerli direttamente nel codice JSON della scheda. Prima dell'applicazione del layout condizionale, la scheda ha quattro righe di testo, come illustrato di seguito.

Implementazione del layout condizionale

Nell'editor del payload della scheda sostituire l'array body con il frammento 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\"}"
    }
]

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.

Senza valutare le espressioni modello, la scheda mostra tutti e quattro i blocchi di testo:

Quando Widgets Board valuta il modello con $host.widgetSize impostato su "small", viene visualizzato solo il blocco di testo di piccole dimensioni insieme al conteggio:

Dopo aver integrato il modello con il provider, ridimensionare il widget fissato nella scheda Widget e verificare che venga visualizzato il blocco di testo corrispondente. Dichiarare ogni dimensione da testare nel manifesto del provider di widget. Un'anteprima generica del Designer senza dati host di Windows non è in grado di verificare queste condizioni.

Associare al contesto dei dati

Nell'esempio viene utilizzata una proprietà di dati denominata count, a cui si fa ${count} riferimento nel primo TextBlock. In fase di esecuzione, il provider invia il payload dei dati all'host del widget. In fase di progettazione immettere il codice JSON seguente nell'editor dati di esempio e abilitare l'anteprima della finestra di progettazione per controllare l'associazione di conteggio. Questi dati di esempio non forniscono le proprietà host Windows separate.

{"count": "2"}

Con {"count": "2"} come dati di esempio, l'espansione del modello sostituisce ${count} con 2 nel primo TextBlock. Controllare questa associazione nel Designer dopo aver abilitato l'anteprima. Controllare le condizioni separate $host.widgetSize nel Widgets Board, come descritto in precedenza.

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

La proprietà type seleziona Action.Execute, che l'host del widget inoltra al callback OnActionInvoked del provider in uso. Usare Action.OpenUrl invece per lo spostamento tramite URL; non richiama il callback del provider. Il titolo fornisce il testo del pulsante e il verb è l'operazione definita dall'app gestita dal provider. Se $host.isUserContextAuthenticated è false, non offrire interazioni Action.Execute; è supportato solo Action.OpenUrl.

Modello di widget completo

Il seguente listato di codice mostra il modello finale per l'interazione del widget di conteggio. Il pulsante Action.Execute richiede un contesto utente autenticato. Verificalo nel Widgets Board del provider; Designer non esegue il gestore di incremento del provider.

{
    "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.Execute",
        "title": "Increment",
        "verb": "inc",
        "$when": "${!$host.isSettingsPayload}"
    },
    {
        "type": "Action.Execute",
        "title": "Update Setting",
        "verb": "setting",
        "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}