Specifica relativa al renderer di schede adattive

La specifica seguente descrive come implementare un renderer di schede adattive in qualsiasi piattaforma dell'interfaccia utente nativa.

Importante

Questo contenuto è un lavoro in corso e potrebbe non essere presente alcuni dettagli. Inviaci un messaggio per sapere se hai domande o commenti.

Analisi del contenuto JSON

Condizioni di errore

1. Un parser DEVE verificare che si tratti di contenuto JSON valido
2. Un parser DEVE eseguire la convalida a fronte dello schema (proprietà obbligatorie e così via)
3. Gli errori sopra riportati DEVONO essere segnalati all'app host (eccezione o equivalente)

Tipi sconosciuti

1. Se vengono rilevati "tipi" sconosciuti, questi DEVONO ESSERE ELIMINATI dal risultato
2. Eventuali modifiche del payload (come nei casi sopra indicati) DOVREBBERO essere segnalate come avvisi all'app host

Proprietà sconosciute

1. Un parser DEVE includere proprietà aggiuntive per gli elementi

Considerazioni aggiuntive

1. La speak proprietà MAY contiene markup SSML e DEVE essere restituita all'app host come specificato

Analisi della configurazione host

1. TODO

Controllo delle versioni

1. Un renderer DEVE implementare una determinata versione dello schema.
2. Il costruttore AdaptiveCardDEVE assegnare alla proprietà version un valore predefinito in base alla versione corrente dello schema.
3. Se un renderer rileva una proprietà version nell'oggetto AdaptiveCard con un valore superiore alla versione supportata, DEVE invece restituire l'oggetto fallbackText.

Elaborazione

Un oggetto AdaptiveCard è costituito da un oggetto body e da actions. L'oggetto body è una raccolta di CardElement di cui un renderer eseguirà l'enumerazione e il rendering nell'ordine.

1. Ogni elemento DEVE estendersi per la larghezza del relativo elemento padre (pensa a display: block in HTML).
2. Un renderer DEVE ignorare qualsiasi tipo di elemento sconosciuto rilevato e continuare a eseguire il rendering del resto del payload.

Text, TextBlock e RichTextBlock

1. Un oggetto TextBlock DEVE occupare un'unica riga, tranne quando la proprietà wrap è impostata su true.
2. Il blocco di testo DOVREBBE tagliare l'eventuale testo in eccesso con i puntini di sospensione (...)

Markdown

1. Le schede adattive consentono l'uso di un sottoinsieme del markdown e DOVREBBE essere fornito il supporto in TextBlock.
2. RichTextBlock NON supporta Markdown e deve essere stilizzato usando le proprietà esposte.
3. Vedi i requisiti di markdown completi.

Funzioni di formattazione

1. TextBlock consente l'uso di funzioni di formattazione DATE/TIME che DEVONO essere supportate in ogni renderer.
2. TUTTI GLI ERRORI DEVONO visualizzare la stringa non elaborata nella scheda. Non vengono usati messaggi descrittivi perché l'obiettivo è quello di far comprendere immediatamente il problema allo sviluppatore.

Immagini

1. Un renderer DOVREBBE consentire alle app host di rilevare quando tutte le immagini HTTP sono state scaricate ed è stato "eseguito il rendering completo" della scheda
2. Un renderer DEVE controllare il parametro maxImageSize della configurazione host durante il download delle immagini HTTP
3. Un renderer DEVE supportare .png e .jpeg
4. Un renderer DOVREBBE supportare le immagini .gif

Comportamento del layout avanzato

Il renderer DEVE occuparsi dei comportamenti seguenti durante il rendering degli elementi della scheda rispetto agli attributi indicati in questo documento.

Il renderer deve gestire i vincoli tenendo conto dei vari fattori, ad esempio margine, riempimento, altezza e larghezza e così via della configurazione degli elementi della scheda e dei relativi elementi figlio.

Larghezza

1. Valori consentiti : autostretch e valori fissi in termini di pixels eweight
2. auto fornisce spazio sufficiente per l'espansione della larghezza (supporta l'espansione minima)
3. stretch occupa la larghezza rimanente (supporta l'espansione massima)

Di seguito vengono descritte le modalità di influenza dei vincoli con combinazioni di larghezza diverse per le colonne

Confronto tra auto e stretch

1. Colonne con auto larghezza e stretch .

• La prima colonna con auto larghezza occupa spazio sufficiente per visualizzare il contenuto e la seconda colonna con stretch larghezza occupa l'intero spazio.

2. Colonne con solo stretch larghezza

• Le colonne con larghezza estesa occupano solo gli spazi rimanenti dopo averlo diviso equamente.

3. auto, stretch e auto

La larghezza della prima e della terza colonna viene adattata per contenere gli elementi in modo sufficiente e la seconda colonna con larghezza estesa occupa lo spazio rimanente.

4. Ordine di visualizzazione degli elementi con auto colonne di larghezza

• Le colonne con auto si posizionano per fornire spazio ampio per il rendering del contenuto.
• In caso di visualizzazioni immagine, le immagini verranno ridimensionate per adattarsi alla larghezza rimanente.
• Nota: le immagini verranno ridimensionate solo per stretch le dimensioni dell'immagine e auto , ma non per la larghezza e l'altezza fisse in pixel.

Confronto tra weights e pixels

1. Colonne con weight combinazione di larghezza e pixel

• La scheda precedente include tre colonne con la configurazione della larghezza seguente:
• Column1: Weight 50, Column2: 100px, Column3: Weight 50
• La larghezza della colonna 2 è determinata da pixel value
• La larghezza della colonna 1 e 3 viene modificata in base a weights e all'oggetto calcolato weight ratio.

2. Colonne con weightattributi e pixel widthauto

• La scheda precedente ha quattro colonne con la configurazione di larghezza seguente:
• Column1: Weight 50, Column2: 100px, Column3: Weight 50 e Column4: auto
• Nota: visualizzazione immagine con auto riduzione delle dimensioni delle colonne di larghezza per adattarsi allo spazio rimanente.

Ordine di precedenza della visualizzazione degli elementi con l'attributo width

px > weight > auto > stretch

Altezza

Valori consentiti - auto e stretch

Gli scenari seguenti descrivono in che modo i vincoli sono interessati da combinazioni di altezza diverse per gli elementi della scheda

1. Gli elementi si espandono liberamente verticalmente quando la scheda non è di altezza fissa

• Entrambe le colonne possono espandersi sufficientemente verticalmente indipendentemente dai auto valori e stretch
• Si tratta della wrap proprietà disabilitata per il blocco di testo.

2. La scheda seguente ha la wrap proprietà abilitata per il blocco di testo.

Spaziatura e separatore

1. La proprietà spacing di ogni elemento influisce sulla quantità di spazio tra l'elemento CORRENTE e quello PRECEDENTE.
2. La spaziatura DEVE ESSERE APPLICATA SOLO quando esiste effettivamente un elemento precedente. Ad esempio, non si applica al primo elemento di una matrice.
3. Un renderer DEVE cercare la quantità di spazio da usare dalla spaziatura di hostConfig per il valore di enumerazione applicato all'elemento corrente.
4. Se l'elemento ha un valore separator impostato su true, DEVE essere tracciata una linea visibile tra l'elemento corrente e quello che lo precede.
5. La linea di separazione DEVE essere tracciata con container.style.default.foregroundColor.
6. Un separatore DEVE ESSERE TRACCIATO SOLO se l'elemento NON È il primo della matrice.
7. Spaziatura - Valori consentiti none, , smalldefault, medium, largeextra large epadding

• L'attributo di spaziatura aggiunge spaziatura tra questo elemento e l'elemento precedente.

• L'attributo di spaziatura non ha alcun effetto quando è il primo elemento nel contenitore di visualizzazione.

• Gli elementi contrassegnati con freccia sono i primi elementi tra i relativi elementi di pari livello, quindi la spaziatura non ha alcun effetto.

2. Separatore - Valori possibili (attiva/disattivata)

• Disegna una linea seperante nella parte superiore dell'elemento.

3. Combinazione di spaziatura e seperatore

• Di seguito sono illustrati i vincoli della spaziatura e della combinazione di seperatore.

• La distanza di spaziatura complessiva viene mantenuta rispetto ai valori forniti.
• Il seperatore viene aggiunto a metà strada nel mezzo della distanza spaziata.

[Nota. È necessario confermare la distanza in cui viene inserito il seperatore nell'area di spaziatura. Sembra il centro]

Stili contenitore

• Fornisce hint di stile per contenitori come colonne e set di colonne
• noneValori consentiti , , defaultemphasisgood, , e attentionwarningaccent
• Queste opzioni di stile predefinite forniscono spaziatura interna per gli elementi all'interno del contenitore e del colore di sfondo

1. Scheda A illustra colonne e set di colonne senza opzioni di stile
2. La scheda B illustra il set di colonne con lo stile Attenzione . Si noti la spaziatura interna all'interno del contenitore columnset e la modifica del colore di sfondo.
3. La scheda C illustra solo le colonne con stili. Analogamente a quello precedente, la colonna include spaziatura interna e modifica dello sfondo.
4. Scheda D illustra colonne e set di colonne con opzioni di stile.

[Nota. È necessario verificare la modalità di determinazione della quantità di riempimento. È determinato dall'host? ]

Sanguinare

• Questa proprietà consente al contenitore, ad esempio colonne e set di colonne, di passare attraverso il relativo elemento padre.
• on Valori possibili e off.

1. Scheda A illustra colonne e set di colonne con stili regolari.
2. La scheda B illustra la prima colonna con opzione smarginata. Il contenuto si è appena smarginato attraverso i limiti del padre.

Dimensioni immagine

Attributo Size

• Valori consentiti : auto, stretchsmall, , medium,large
• auto : le immagini verranno ridimensionate per adattarsi, se necessario, ma non aumentano le prestazioni per riempire l'area.
• stretch : immagine con riduzione delle prestazioni e adattabilità in base alle esigenze.
• small, medium e large: l'immagine viene visualizzata con una larghezza fissa, in cui la larghezza è determinata dall'host.

1. Confronto tra auto e stretch

2. Combinazione Larghezza colonna e Dimensioni immagine

• In genere, le colonne con stretch larghezza consentono alle immagini di ottenere liberamente stretch dimensioni.
• Le colonne con auto larghezza consentono all'immagine di occupare spazio esatto indipendentemente dalle auto dimensioni e stretch dall'immagine.
• La larghezza delle colonne ha la precedenza per determinare le dimensioni dell'immagine in questa disposizione.

Attributo image Width (in pixels)

• In questo modo viene fornita la larghezza desiderata sullo schermo dell'immagine.
• size la proprietà viene sottoposta a override quando viene specificato un valore

• La colonna con auto larghezza avrà una precedenza maggiore rispetto stretch a quella di fornire spazio per il contenuto dell'immagine in questa disposizione.

Larghezza colonna (spessore e pixel) e Dimensione immagine (combinazione automatica e estensione)

• Le immagini con auto dimensioni impiegano spazio sufficiente per l'espansione (o le scalabilità ridotta) all'interno dei vincoli di colonna di weight e pixel larghezza.
• Le immagini con stretch dimensioni possono espandersi per riempire lo spazio rimanente entro i vincoli di colonna weight e pixel larghezza.

Riepilogo layout avanzato

• La larghezza della colonna ha la precedenza per determinare le dimensioni dell'immagine rispetto alle dimensioni dell'immagine (auto, stretch, larghezza minima e così via).
• La precedenza della larghezza della colonna presa per visualizzarne il contenuto sufficientemente - px>weight>auto>stretch
• L'immagine size (auto, stretch) viene ignorata quando viene fornito Image width e height in px.
• L'attributo dimensioni immagine stretch è di alto livello per l'immagine solo quando è presente spazio rimanente e la colonna automatica nonauto.
• Un'immagine si estende fino al limite in cui mantiene le proporzioni nello spazio disponibile nella colonna. A sua volta, l'altezza si espande liberamente.
• Spacing l'attributo non avrà alcun effetto quando è il primo o l'unico elemento tra i suoi elementi di pari livello.

Azioni

1. Se la proprietà supportsInteractivity di HostConfig è false, un renderer NON DEVE eseguire il rendering di alcuna azione.
2. La proprietà actionsDEVE essere sottoposta a rendering come pulsanti in una specie di barra delle azioni, in genere nella parte inferiore della scheda.
3. Quando un pulsante viene toccato, DEVE consentire all'app host di gestire l'evento.
4. L'evento DEVE passare tutte le proprietà associate con l'azione.
5. L'evento DEVE passare l'oggetto AdaptiveCard che è stato eseguito.

Azione	Comportamento
Action.OpenUrl	Apre un URL esterno per la visualizzazione
Action.ShowCard	Richiede che una scheda secondaria venga visualizzata all'utente.
Azione.Invia	Richiede la raccolta di tutti gli elementi di input in un oggetto che ti viene quindi inviato tramite un metodo definito dall'applicazione host.
Action.Execute	(Introdotto nella versione 1.4) Chiedere che tutti gli elementi di input vengano raccolti in un oggetto che viene quindi inviato all'utente tramite la "pipeline di azione universale"

Action.OpenUrl

1. Action.OpenUrl DOVREBBE aprire un URL usando il meccanismo della piattaforma nativa.
2. Se questo non è possibile, DEVE generare un evento nell'app host per gestire l'apertura dell'URL. Questo evento DEVE consentire all'app host di eseguire l'override del comportamento predefinito, ad esempio consentire l'apertura dell'URL all'interno della rispettiva app.

Action.ShowCard

1. L'azione Action.ShowCardDEVE essere supportata in qualche modo, in base all'impostazione di hostConfig. Sono disponibili due modalità: inline e popup. Le schede inline DOVREBBERO attivare/disattivare la visibilità della scheda automaticamente. In modalità popup DOVREBBE essere generato un evento nell'app host per mostrare la scheda in qualche modo.

Azione.Invia

• Action.Submit l'elemento raccoglie i campi di input, unisce con il campo dati facoltativo e invia un evento al client.
• Una differenza significativa nel comportamento degli elementi è presente tra la versione 1.x e la versione 2.x del renderer ACL.

L'azione di invio si comporta come l'invio di un modulo HTML, ad eccezione del fatto che, quando il codice HTML in genere attiva un post HTTP, le schede adattive lasciano a ogni app host la possibilità di determinare il significato di "inviare".

1. Quando DEVE essere generato un evento, l'utente tocca l'azione richiamata.
2. La proprietà dataDEVE essere inclusa nel payload di callback.
3. Per Action.Submit, un renderer DEVE raccogliere tutti gli input nella scheda e recuperare i relativi valori.

• 1.x Renderer - Gli input vengono raccolti da tutti i campi indipendentemente dalla posizione in cui è presente il campo di input nella gerarchia.
• 2.x Renderer - Gli input vengono raccolti dai campi presenti nel contenitore padre o come elemento di pari livello dell'elemento Action.Submit .

Action.Execute (dettagli in arrivo più avanti)

Action.Execute è stato introdotto nella versione 1.4. Verranno fornite indicazioni sull'implementazione per gli SDK in un secondo momento. Contattare se si hanno domande su questo argomento.

selectAction

1. Se la proprietà supportedInteractivity di Host Config è false, selectActionNON DEVE soggetta a rendering come destinazione del tocco.
2. Image, ColumnSet e Column offrono una proprietà selectAction che DOVREBBE essere eseguita quando l'utente la richiama, ad esempio toccando l'elemento.

Input

1. Se la proprietà supportsInteractivity di HostConfig è false, un renderer NON DEVE eseguire il rendering di alcun input.
2. Gli input DOVREBBERO essere sottoposti a rendering con la massima fedeltà possibile. Ad esempio, un oggetto Input.Date idealmente offre una selezione data a un utente, ma se questo non è possibile nello stack dell'interfaccia utente, il renderer DEVE eseguire il fallback al rendering di una casella di testo standard.
3. Un renderer DOVREBBE visualizzare l'oggetto placeholderText, se possibile.
4. L'associazione del valore di input DEVE essere preceduta adeguatamente da caratteri di escape.
5. Prima della versione 1.3, un renderer NON deve implementare la convalida dell'input. Gli utenti di schede adattive devono pianificare la convalida dei dati ricevuti sul loro lato.
6. Le etichette di input e la convalida sono state introdotte nella versione 1.3 dello schema delle schede adattive. È necessario prestare particolare attenzione per eseguire il rendering dell'etichetta associata, degli hint di convalida e dei messaggi di errore.

Api di applicazione di stili, personalizzazione ed estendibilità

Ogni SDK deve fornire un certo livello di flessibilità per ospitare le app per controllare lo stile complessivo ed estendere lo schema come previsto.

Configurazione dell'host

• TODO: quali valori devono essere i valori predefiniti? La condivisione dovrebbe essere totale? È necessario incorporare un file hostConfig.json comune nei dati binari?

HostConfig è un oggetto di configurazione condivisa che specifica il modo in cui un renderer di schede adattive genera l'interfaccia utente.

Ciò consente di condividere le proprietà indipendenti dalla piattaforma tra i renderer in piattaforme e dispositivi diversi. Consente inoltre di creare strumenti che danno un'idea dell'aspetto che avrebbe la scheda per un determinato ambiente.

1. I renderer DEVONO esporre un parametro di configurazione host alle app host
2. Tutti gli elementi DEVONO avere uno stile in base alle rispettive impostazioni di configurazione host

Applicazione di stili della piattaforma nativa

1. Ogni tipo di elemento DOVREBBE associare uno stile della piattaforma nativa all'elemento generato dell'interfaccia utente. Ad esempio, in HTML è stata aggiunta una classe CSS ai tipi di elemento e in XAML viene assegnato uno stile specifico.

Estendibilità

1. Un renderer DEVE consentire alle app host di eseguire l'override dei renderer di elementi predefiniti, ad esempio sostituire il rendering di TextBlock con la propria logica.
2. Un renderer DEVE consentire alle app host di registrare tipi di elementi personalizzati, ad esempio aggiungere il supporto per un elemento Rating personalizzato.
3. Un renderer DEVE consentire alle app host di rimuovere il supporto per un elemento predefinito, ad esempio rimuovere Action.Submit se non vogliono che sia supportato.

Eventi

1. Un renderer DOVREBBE generare un evento quando la visibilità di un elemento è cambiata, consentendo all'app host di scorrere la scheda in posizione.