Freigeben über

Power FxYAML-Formelgrammatik

  • Artikel

Anmerkung

Microsoft Power Fx ist der neue Name für die Formelsprache für Canvas-Apps. Diese Artikel werden ständig weiterentwickelt, da wir die Sprache aus Canvas-Apps extrahieren, in andere Microsoft Power Platform-Produkte integrieren und als Open Source zur Verfügung stellen. Beginnen Sie mit der Microsoft Power Fx-Übersicht, um eine Einführung in die Sprache zu erhalten.

Microsoft Power Fx verfügt über eine bewährte Grammatik für Ausdrücke, die auf Excel basieren. Bei Verwendung in Power Apps und anderen Hosts, bei denen die Benutzeroberfläche die Bindung von Name zu Ausdruck für eine Formel bereitstellt, gibt es keine Standardmethode zum Bearbeiten der Formelbindung als Text.

Wir haben den Industriestandard YAML als unsere Sprache für diese Bindung ausgewählt. Es gibt bereits eine große Anzahl von Editoren, Tools und Bibliotheken für die Arbeit mit YAML. Dieser Artikel beschreibt, wie wir Formeln in YAML darstellen.

Derzeit unterstützen wir nur eine eingeschränkte Teilmenge von YAML. Es werden nur die in diesem Artikel beschriebenen Konstrukte unterstützt.

Hier ist nicht alles dargestellt, was eine Canvas-App definiert. Zusätzliche Informationen fließen durch andere Dateien, die das Tool erstellt und verwendet.

Vorangestelltes Gleichheitszeichen

In erster Linie müssen alle Ausdrücke mit einem vorangestellten Gleichheitszeichen = beginnen:

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

Wir verwenden = auf diese Weise aus drei Gründen:

  • Dies steht im Einklang mit der Verwendung eines vorangestellten =, um einen Ausdruck an eine Zelle zu binden.
  • Es entgeht effektiv der Syntax der Formelsprache, sodass YAML nicht versucht, sie zu analysieren. Normalerweise würde YAML text: 1:00 als Minuten und Sekunden behandeln und in eine Zahl umwandeln. Durch Einfügen eines =, verwendet YAML seine impliziten Typisierungsregeln nicht und Formeln werden nicht beschädigt. Die Verwendung von = deckt die meisten Fälle ab, aber nicht alle, und diese Ausnahmen werden im folgenden Abschnitt beschrieben, Einzeilige Formeln.
  • In Zukunft werden wir beide Formeln (beginnt mit =) als auch Nicht-Formen (kein =) in derselben Datei, genau wie bei Excel. Dies kann in YAML- und in Nicht-YAML-Dateien für alle Microsoft Power Platform-Quelldateien erfolgen. Überall dort, wo eine Formel unterstützt wird, unterscheidet der Einzug = einen Power Apps Formelausdruck aus einem statischen Skalarwert.

Einzelne Formeln

Einzeilige Formeln werden in folgender Form geschrieben:

Name:SPACE=Ausdruck

Der Abstand zwischen dem Doppelpunkt und dem Gleichheitszeichen muss YAML-konform sein. Das Gleichheitszeichen stört die normale Interpretation des Ausdrucks durch YAML, sodass der Rest der Zeile als Power Fx interpretiert werden kann. Zum Beispiel:

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

Das Nummernzeichen # und der Doppelpunkt : sind in einzeiligen Formeln nirgendwo zulässig, selbst wenn sie in einer Textzeichenfolge oder einem Bezeichnernamen in Anführungszeichen stehen. Sie müssen die Formel als mehrzeilige Formel ausdrücken, um ein Numernzeichen oder einen Doppelpunkt zu verwenden. Das Nummernzeichen wird in YAML als Kommentar und der Doppelpunkt als neue Namenszuordnung interpretiert. Verwenden Sie zum Hinzufügen eines Kommentars zu einem einzeiligen Kommentar den Power Fx-Zeilenkommentar beginnend mit //.

Die Verwendung von normalem YAML mit einfachen Anführungszeichen und C-ähnlichen umgekehrte Schrägstriche als Escapezeichen wird nicht unterstützt. Verwenden Sie stattdessen eine mehrzeilige Formel. Dies dient der Konsistenz und erleichtert das Ausschneiden/Einfügen zwischen den Formelleisten in Power Apps Studio und YAML-Quelldateien.

Weitere Informationen in der Canvas-App-Dokumentation Operatoren und Bezeichner für Details zu zulässigen Namen und der Struktur eines Ausdrucks.

Mehrzeilige Formeln

Formeln können mithilfe der Blockskalarindikatoren von YAML mehrere Zeilen umfassen:

Name:SPACE ( | oder |+ oder |- ) =AusdruckszeileAusdruckszeile …

Alle Zeilen, die Teil des Blocks sind, müssen mindestens ein Leerzeichen von der Ebene der ersten Zeile entfernt eingerückt sein.

Beispiel: ''

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

Wir akzeptieren alle Formen der mehrzeiligen YAML-Skalarnotation beim Import, einschließlich zum Beispiel >+. Um sicherzustellen, dass Leerzeichen ordnungsgemäß erhalten bleiben, werden nur |, |+ oder |- erzeugt.

Komponenteninstanz

Komponenten werden mithilfe der YAML-Objektnotation instanziiert. Der Typ des Objekts wird mit dem As-Operator als Teil des linken YAML-Tags eingerichtet. Bei Containersteuerelementen können Objekte verschachtelt werden.

NameAsKomponententyp [ .Komponentenvorlage ] : ( Einzeilige Formel oder Mehrzeilige Formel oder Objektinstanz ) …

Alle Zeilen, die Teil des Blocks sind, müssen mindestens ein Leerzeichen von der Ebene der ersten Zeile entfernt eingerückt sein.

Beispiel: ''

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
            )

Komponententyp kann jede beliebige Canvas-Komponente oder Steuerung sein. Basistypen wie Nummer werden nicht unterstützt.

Component-Template ist ein optionaler Spezifizierer für Komponenten, die unterschiedliche Vorlagen haben, wie z. B. die Galerie. Nicht alle Komponenten verfügen über Vorlagen.

Wenn Name Sonderzeichen enthält und in einfache Anführungszeichen gesetzt wird, muss der gesamte Ausdruck links des Doppelpunkts mit Escapezeichen versehen werden. Dazu kann eine der folgenden Methoden verwendet werden:

  • Verwenden Sie einfache Anführungszeichen, um die gesamte linke Seite umzubrechen. Dazu müssen die vorhandenen einfachen Anführungszeichen zweimal verwendet werden: 
    '''A name with a space'' As Gallery':
  • Verwenden Sie doppelte Anführungszeichen, um die gesamte linke Seite umzubrechen. Achten Sie jedoch darauf, dass der Name keine doppelten Anführungszeichen enthält: 
    "'A name with a space' As Gallery":

Komponentendefinition

In ähnlicher Weise werden Komponenten definiert, indem eine Instanz eines der unterstützten Basistypen erstellt wird. Die Basistypen können nicht direkt instanziiert werden. Innerhalb einer Objektdefinition können Eigenschaften zu dem hinzugefügt werden, was der Basistyp bereitstellt.

Die unterstützten Basistypen sind: Canvas-Komponenten

Einfache Eigenschaftsdefinition

Komponenten verwenden Eigenschaften, um mit der App zu kommunizieren, in der sie gehostet werden.

Name: ( Einzeiliger Ausdruck oder Mehrzeiliger Ausdruck )

Der Typ der Formel wird durch den Typ des Ausdrucks impliziert.

Für Eingabeeigenschaften bietet der Ausdruck die Standardeinstellung, die in die App eingefügt wird, wenn die Komponente instanziiert wird. Der Hersteller kann diesen Ausdruck nach Belieben ändern, den Typ jedoch nicht.

Für Ausgabeeigenschaften liefert der Ausdruck die durchzuführende Berechnung. Der Hersteller kann diesen Ausdruck nicht ändern, er ist mit der Komponente verknüpft.

Derzeit sind alle Eigenschaften vom Typ „Datenfluss“ und können keine Nebeneffekte enthalten.

Derzeit werden hier keine zusätzlichen Metadaten zur Eigenschaft definiert, sondern in den anderen Dateien der .msapp-Datei definiert, zum Beispiel die Beschreibung der Eigenschaft.

Beispiel: ''

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

YAML Kompatibilität

YAML Kommentare

Durch das Nummernzeichen # begrenzte YAML-Zeilenkommentare werden nirgendwo im Quellformat beibehalten. Begrenzen Sie stattdessen innerhalb einer Formel die Zeilenkommentare mit //-Zeichen oder Blockkommentare mit /* und */. Weitere Informationen: Kommentare

Fehler für häufige Fallstricke

Es gibt einige Stellen, an denen die Power Fx- und YAML-Grammatiken nicht kompatibel sind oder für einen Benutzer verwirrend sein können. In diesen Fällen wird ein Fehler ausgegeben.

Beispielsweise im folgenden:

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

Das Nummernzeichen # wird von YAML als Kommentar behandelt, obwohl es in eine von Excel als Textzeichenfolge betrachtete Zeichenfolge eingebettet ist (in doppelte Anführungszeichen gesetzt). Um Verwirrung zu vermeiden, wird in diesem Fall beim Import ein Fehler ausgegeben. Stattdessen kann ein mehrzeiliges YAML-Formular verwendet werden.

Im Falle des Wertes für record betrachtet YAML a: und b: als eine andere Namenszuordnungsbindung. Mit YAML kann dieselbe Namenszuordnung wiederverwendet werden, wobei die letzte alle vorherigen Definitionen automatisch überschreibt. Da dies für einen Low-Code-Hersteller verwirrend sein kann und zum Verlust einer Eigenschaftsformel führen kann, wird ein Fehler ausgegeben, wenn derselbe Name zweimal auftritt.