Condividi tramite

Power FxGrammatica delle formule YAML

  • Articolo

Nota

Microsoft Power Fx è il nuovo nome per il linguaggio delle formule per le app canvas. Questi articoli sono in fase di elaborazione poiché estraiamo il linguaggio dalle app canvas, lo integriamo con altri prodotti di Microsoft Power Platform e lo rendiamo disponibile come open source. Inizia con la panoramica di Microsoft Power Fx per un'introduzione al linguaggio.

Microsoft Power Fx ha una grammatica consolidata per le espressioni basate su Excel. Tuttavia, se utilizzato in Power Apps e altri host in cui l'interfaccia utente fornisce l'associazione nome-espressione per una formula, non esiste un modo standard per modificare l'associazione della formula come testo.

Abbiamo selezionato lo standard del settore YAML come linguaggio per questa associazione. Esiste già un gran numero di editor, strumenti e librerie che funzionano con YAML. Questo articolo descrive come rappresentiamo le formule in YAML.

In questo momento, supportiamo solo un sottoinsieme limitato di YAML. Sono supportati solo i costrutti descritti in questo articolo.

Non tutto ciò che definisce un'app canvas è rappresentato qui; ulteriori informazioni passano attraverso altri file che lo strumento produce e consuma.

Segno di uguale iniziale

Innanzitutto, tutte le espressioni devono iniziare con un segno di uguale iniziale =:

Visible: =true
X: =34
Text: |
	="Hello, " &
	"World"

Noi usiamo = in questo modo per tre motivi:

  • È coerente con Excel, che utilizza un segno = iniziale per associare un'espressione a una cella.
  • Applica correttamente l'escape alla sintassi del linguaggio delle formule in modo che YAML non tenti di analizzarla. Normalmente, YAML tratterebbe text: 1:00 come minuti e secondi, convertendolo in un numero. Inserendo un segno =, YAML non utilizzerà le regole di tipizzazione implicite e le formule non verranno danneggiate. L'utilizzo di = copre la maggior parte dei casi, ma non tutti, e tali eccezioni sono descritte nella sezione seguente, Formule a riga singola.
  • In futuro, verranno supportate le formule (inizia con =) e le non formule (nessun =) nello stesso file, proprio come in Excel. Questo sarà possibile in file YAML e non YAML allo stesso modo nei file di origine di Microsoft Power Platform. Ovunque sia supportata una formula, l'intestazione = differenzia un'espressione delle formule di Power Apps da un valore scalare statico.

Formule a riga singola

Le formule a riga singola sono scritte nella forma:

Nome:SPACE=Espressione

Lo spazio tra i due punti e il segno di uguale deve essere conforme a YAML. Il segno di uguale interrompe la normale interpretazione dell'espressione da parte di YAML, consentendo di interpretare il resto della riga come Power Fx. Ad esempio: 

Text1: ="Hello, World"
Text2: ="Hello " & ", " & "World"
Number1: =34
Boolean1: =true
Time1: =1:34

Il segno del cancelletto # e i due punti : non sono consentiti in nessuna posizione nelle formule a riga singola, anche se si trovano in una stringa di testo tra virgolette o in un nome identificativo. Per utilizzare un cancelletto o i due punti, è necessario esprimere la formula come formula su più righe. Il segno del cancelletto viene interpretato come un commento in YAML, mentre i due punti vengono interpretati come una nuova mappa del nome in YAML. Per aggiungere un commento a un commento su riga singola, utilizza il commento di riga Power Fx che inizia con //.

L'uso del normale escape YAML con virgolette singole e barre rovesciate tipo C non è supportato; usa invece una formula su più righe. L'obiettivo è garantire coerenza e facilitare le operazioni di taglia e incolla tra la barra della formula in Power Apps Studio e i file di origine YAML.

Vedi la documentazione sugli operatori e gli identificatori delle app canvas per i dettagli sui nomi consentiti e sulla struttura di un'espressione.

Formule su più righe

Le formule possono estendersi su più righe utilizzando gli indicatori scalari di blocco di YAML:

Nome:SPACE ( | o |+ o |- ) =Linea di espressioneLinea di espressione ...

Tutte le righe che fanno parte del blocco devono essere rientrate di almeno uno spazio dal livello della prima riga.

Ad esempio: 

Text1: |
    ="Hello, World"
Text2: |
    ="Hello" &
    "," &
    "World"

Tutte le forme di notazioni scalari multiriga di YAML sono accettate nell'importazione, incluso ad esempio >+. Tuttavia, per garantire che gli spazi vuoti vengano conservati correttamente, sono prodotti solo |, |+ o |-.

Istanza del componente

Le istanze dei componenti vengono create utilizzando la notazione degli oggetti YAML. Il tipo di oggetto viene stabilito con l'operatore As come parte del tag YAML sul lato sinistro. Per i controlli contenitore, gli oggetti possono essere nidificati.

NomeAsTipo-componente [ .Modello-componente ] : ( Formula-a-riga-singola o Formula-a-riga-multipla o Istanza-oggetto ) ...

Tutte le righe che fanno parte del blocco devono essere rientrate di almeno uno spazio dal livello della prima riga.

Ad esempio: 

Gallery1 As Gallery.horizontalGallery:
    Fill: = Color.White
    Label1 As Label:
        Text: ="Hello, World"
        X: =20
        Y: =40
        Fill: |
            =If( Lower( Left( Self.Text, 6 ) ) = "error:",
                Color.Red,
                Color.Black
            )

Component-Type può essere qualsiasi componente o controllo canvas. I tipi di base, come Numero, non sono supportati.

Component-Template è uno specificatore facoltativo per i componenti che hanno modelli diversi, come la Galleria. Non tutti i componenti dispongono di modelli.

Se Nome contiene caratteri speciali ed è racchiuso tra virgolette singole, l'intera frase a sinistra dei due punti dovrà essere preceduta da caratteri di escape. Questo può essere fatto in uno dei seguenti modi:

  • Utilizzando le virgolette singole per eseguire il wrapping dell'intero lato sinistro, il che richiede che le virgolette singole esistenti vengano utilizzate due volte: 
    '''A name with a space'' As Gallery':
  • Utilizzando le virgolette doppie per eseguire il wrapping dell'intero lato sinistro, ma accertandosi che non vi siano virgolette doppie nel nome: 
    "'A name with a space' As Gallery":

Definizione dei componenti

Allo stesso modo, i componenti vengono definiti creando un'istanza di uno dei tipi di base supportati. Le istanze dei tipi di base non possono essere create direttamente. All'interno di una definizione di oggetto, è possibile aggiungere proprietà a ciò che fornisce il tipo di base.

I tipi di dati supportati sono: CanvasComponent

Definizione della proprietà semplice

I componenti usano le proprietà per comunicare con l'app in cui sono ospitati.

Nome: ( Espressione su una sola riga o Espressione su più righe )

Il tipo di formula è implicito dal tipo di espressione.

Per le proprietà di input, l'espressione fornisce l'impostazione predefinita da inserire nell'app quando viene creata un'istanza del componente. Il creatore può modificare questa espressione come meglio crede, ma non può cambiare il tipo.

Per le proprietà di output, l'espressione fornisce il calcolo da eseguire. Il creatore non può modificare questa espressione poiché è incapsulata nel componente.

Al momento, tutte le proprietà sono solo flusso di dati e non possono contenere effetti collaterali.

Al momento, i metadati aggiuntivi sulla proprietà non sono definiti qui, ma sono invece definiti negli altri file del file .msapp, ad esempio la descrizione della proprietà.

Ad esempio: 

DateRangePicker As CanvasComponent:
    DefaultStart: |-
		=// input property, customizable default for the component instance
		Now()                      
    DefaultEnd: |-
		=// input property, customizable default for the component instance
		DateAdd( Now(), 1, Days )    
    SelectedStart: =DatePicker1.SelectedDate   // output property
    SelectedEnd: =DatePicker2.SelectedDate     // output property

Compatibilità YAML

Commenti YAML

I commenti di riga YAML delimitati dal segno del cancelletto # non vengono conservati in nessuna posizione nel formato di origine. Invece, all'interno di una formula, delimita i commenti di riga con i caratteri // o blocca i commenti con /* e */. Altre informazioni: Commenti

Errori per insidie comuni

Ci sono alcuni punti in cui le grammatiche Power Fx e YAML sono incompatibili o potrebbero creare confusione per un utente. In questi casi, viene generato un errore.

Ad esempio, in:

Text: ="Hello #PowerApps"
Record: ={ a: 1, b: 2 }

il segno del cancelletto # viene considerato come un commento da YAML, anche se è incorporato in quella che Excel considera una stringa di testo (racchiusa tra virgolette doppie). Per evitare confusione, in questo caso verrà generato un errore durante l'importazione. In alternativa, è possibile utilizzare un modulo multiriga di YAML.

Nel caso del valore per record, YAML considera a: e b: come un'altra associazione della mappa dei nomi. YAML consente di riutilizzare la stessa mappa dei nomi, con l'ultima che sovrascrive silenziosamente qualsiasi definizione precedente. Poiché questo può creare confusione per un creatore con uso limitato di codice e può causare la perdita di una formula di proprietà, viene generato un errore se lo stesso nome viene rilevato due volte.