Linguaggio del modello di Schede adattive
La creazione di modelli consente di separare i dati dal layout nella scheda adattiva. Il linguaggio del modello è la sintassi usata per creare un modello.
Per una panoramica della creazione di modelli di schede adattive, leggi l'argomento specifico.
Importante
Modifiche importanti apportate alla versione finale candidata di maggio 2020
Abbiamo lavorato intensamente per il rilascio della creazione di modelli e abbiamo finalmente raggiunto l'obiettivo. Abbiamo dovuto apportare alcune piccole modifiche importanti, man mano che ci avvicinavamo alla data del rilascio.
- La sintassi di binding è cambiata da
{...}
a${...}
.- Ad esempio,
"text": "Hello {name}"
diventa"text": "Hello ${name}"
- Ad esempio,
La scrittura di un modello è semplice quanto la sostituzione del contenuto "non statico" della scheda con "espressioni di binding".
{
"type": "TextBlock",
"text": "Matt"
}
{
"type": "TextBlock",
"text": "${firstName}"
}
- Le espressioni di binding possono essere posizionate in qualsiasi punto in cui è presente contenuto statico
- La sintassi di binding inizia con
${
e termina con}
, ad esempio${myProperty}
- Usa Notazione Dot per accedere agli oggetti secondari di una gerarchia di oggetti, ad esempio
${myParent.myChild}
- Una gestione regolare dei valori null garantisce che non vengano generate eccezioni se accedi a una proprietà null in un oggetto grafico
- Usa la sintassi dell'indicizzatore per recuperare le proprietà in base alla chiave o agli elementi di una matrice, ad esempio
${myArray[0]}
Ora che disponi di un modello, devi specificare i dati che lo rendono completo. A questo scopo, sono disponibili due opzioni:
- Opzione A: inline all'interno del payload del modello. Puoi specificare i dati inline all'interno del payload del modello
AdaptiveCard
. Per eseguire questa operazione, aggiungi semplicemente un attributo$data
all'oggetto radiceAdaptiveCard
. - Opzione B: come oggetto dati separato. Con questa opzione, puoi specificare due oggetti separati nell'SDK per la creazione di modelli in fase di esecuzione:
template
edata
. Si tratta dell'approccio più comune, dal momento che, in genere, si crea innanzitutto un modello e i dati dinamici vengono specificati in un secondo momento.
{
"type": "AdaptiveCard",
"$data": {
"employee": {
"name": "Matt",
"manager": { "name": "Thomas" },
"peers": [{
"name": "Andrew"
}, {
"name": "Lei"
}, {
"name": "Mary Anne"
}, {
"name": "Adam"
}]
}
},
"body": [
{
"type": "TextBlock",
"text": "Hi ${employee.name}! Here's a bit about your org..."
},
{
"type": "TextBlock",
"text": "Your manager is: ${employee.manager.name}"
},
{
"type": "TextBlock",
"text": "3 of your peers are: ${employee.peers[0].name}, ${employee.peers[1].name}, ${employee.peers[2].name}"
}
]
}
In alternativa (e con maggiore probabilità), creerai un modello di scheda riutilizzabile senza includere i dati. Questo modello può essere archiviato come file e aggiunto al controllo del codice sorgente.
EmployeeCardTemplate.json
{
"type": "AdaptiveCard",
"body": [
{
"type": "TextBlock",
"text": "Hi ${employee.name}! Here's a bit about your org..."
},
{
"type": "TextBlock",
"text": "Your manager is: ${employee.manager.name}"
},
{
"type": "TextBlock",
"text": "3 of your peers are: ${employee.peers[0].name}, ${employee.peers[1].name}, ${employee.peers[2].name}"
}
]
}
Puoi quindi caricarlo e fornire i dati in fase di esecuzione tramite gli SDK per la creazione di modelli.
Esempio di JavaScript
Uso del pacchetto adaptivecards-templating.
var template = new ACData.Template({
// EmployeeCardTemplate goes here
});
// Specify data at runtime
var card = template.expand({
$root: {
"employee": {
"name": "Matt",
"manager": { "name": "Thomas" },
"peers": [{
"name": "Andrew"
}, {
"name": "Lei"
}, {
"name": "Mary Anne"
}, {
"name": "Adam"
}]
}
}
});
// Now you have an AdaptiveCard ready to render!
Adaptive Cards Designer è stato aggiornato per supportare la creazione di modelli.
Provala all'indirizzo: https://adaptivecards.io/designer .
- Editor dati di esempio : specificare i dati di esempio qui per visualizzare la scheda associata ai dati quando in modalità di anteprima. In questo riquadro è presente un pulsante di piccole dimensioni per popolare la struttura dati dai dati di esempio esistenti.
- Preview Mode: premi il pulsante della barra degli strumenti per passare dall'esperienza di modifica a quella di anteprima dei dati di esempio e viceversa.
- Open Sample: fai clic su questo pulsante per aprire vari payload di esempio.
Esistono alcune parole chiave riservate per accedere a diversi ambiti di binding.
{
"${<property>}": "Implicitly binds to `$data.<property>`",
"$data": "The current data object",
"$root": "The root data object. Useful when iterating to escape to parent object",
"$index": "The current index when iterating"
}
Per assegnare un contesto dati a qualsiasi elemento, aggiungi all'elemento un attributo $data
.
{
"type": "Container",
"$data": "${mySubObject}",
"items": [
{
"type": "TextBlock",
"text": "This TextBlock is now scoped directly to 'mySubObject': ${mySubObjectProperty}"
},
{
"type": "TextBlock",
"text": "To break-out and access the root data, use: ${$root}"
}
]
}
- Se la proprietà
$data
di un elemento Adaptive Card è associata a una matrice, l'elemento Adaptive Card verrà ripetuto per ciascun elemento della matrice. - Tutte le espressioni di binding (
${myProperty}
) usate nei valori delle proprietà saranno limitate all'ambito del singolo elemento all'interno della matrice. - Se è stato eseguito il binding a una matrice di stringhe, usa
${$data}
per accedere al singolo elemento stringa, ad esempio"text": "${$data}"
Ad esempio, l'elemento TextBlock
seguente sarà ripetuto tre volte poiché il relativo $data
è una matrice. Si noti che la proprietà text
è associata alla proprietà name
di un singolo oggetto all'interno della matrice.
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"$data": [
{ "name": "Matt" },
{ "name": "David" },
{ "name": "Thomas" }
],
"text": "${name}"
}
]
}
Risultato:
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Matt"
},
{
"type": "TextBlock",
"text": "David"
}
{
"type": "TextBlock",
"text": "Thomas"
}
]
}
Nessun linguaggio per la creazione di modelli è completo senza una suite completa di funzioni helper. La creazione di modelli di schede adattive si basa sul linguaggio di espressioni adattive, uno standard aperto per la dichiarazione di espressioni che possono essere valutate su molte piattaforme diverse. Si tratta di un superset appropriato di "app per la logica", quindi puoi usare una sintassi simile a quella di Power Automate e così via.
Ecco un piccolo campionamento delle funzioni predefinite.
Vedi l'elenco completo delle funzioni predefinite del linguaggio delle espressioni adattive.
- if(expression, trueValue, falseValue)
Esempio di if
{
"type": "TextBlock",
"color": "${if(priceChange >= 0, 'good', 'attention')}"
}
- json(jsonString) - Analizza una stringa JSON
Esempio di json
Si tratta di una risposta DevOps di Azure in cui la proprietà message
è una stringa serializzata in JSON. Per accedere ai valori all'interno della stringa, dobbiamo usare la funzione json
nel modello.
Dati
{
"id": "1291525457129548",
"status": 4,
"author": "Matt Hidinger",
"message": "{\"type\":\"Deployment\",\"buildId\":\"9542982\",\"releaseId\":\"129\",\"buildNumber\":\"20180504.3\",\"releaseName\":\"Release-104\",\"repoProvider\":\"GitHub\"}",
"start_time": "2018-05-04T18:05:33.3087147Z",
"end_time": "2018-05-04T18:05:33.3087147Z"
}
Utilizzo
{
"type": "TextBlock",
"text": "${json(message).releaseName}"
}
Risultato
{
"type": "TextBlock",
"text": "Release-104"
}
Le funzioni personalizzate sono supportate tramite le API negli SDK per la creazione di modelli.
Per eliminare un intero elemento nel caso in cui venga soddisfatta una condizione, usa la proprietà $when
. Se il valore di $when
risulta essere false
, l'elemento non verrà visualizzato per l'utente.
{
"type": "AdaptiveCard",
"$data": {
"price": "35"
},
"body": [
{
"type": "TextBlock",
"$when": "${price > 30}",
"text": "This thing is pricy!",
"color": "attention",
},
{
"type": "TextBlock",
"$when": "${price <= 30}",
"text": "Dang, this thing is cheap!",
"color": "good"
}
]
}
Attualmente non è disponibile alcun supporto per la composizione di parti del modello. Tuttavia, stiamo esplorando varie opzioni e ci auguriamo di condividere presto altre informazioni. Si accetta qualsiasi suggerimento.
Accedi alla pagina degli esempi aggiornati per esplorare tutti i tipi di nuove schede basate su modelli.