Power FxGrammatica van YAML-formules

  • Artikel

Notitie

Microsoft Power Fx is de nieuwe naam voor de formuletaal voor canvas-apps. Aan deze artikelen wordt gewerkt terwijl we de taal extraheren uit canvas-apps en deze integreren met andere Microsoft Power Platform-producten en het beschikbaar maken als open source. Begin met het Microsoft Power Fx-overzicht voor een inleiding in de taal.

Microsoft Power Fx heeft een goed opgezette grammatica voor expressies op basis van Excel. Bij gebruik in Power Apps en andere hosts waar UI de naam-naar-expressie-binding voor een formule biedt, is er echter geen standaardmanier om de formulebinding als tekst te bewerken.

We hebben de industriestandaard geselecteerd YAML als onze taal voor deze binding. Er is al een groot aantal editors, tools en bibliotheken om met YAML te werken. Dit artikel beschrijft hoe we formules weergeven in YAML.

Op dit moment ondersteunen we slechts een beperkte subset van YAML. Alleen de constructies die in dit artikel worden beschreven, worden ondersteund.

Niet alles wat een canvas-app definieert, wordt hier weergegeven; aanvullende informatie stroomt door andere bestanden die de tool produceert en verbruikt.

Voorafgaand gelijkteken

Allereerst moeten alle expressies worden voorafgegaan door een gelijkteken =:

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

Wij gebruiken het teken = op deze manier om drie redenen:

  • Dit is consistent met Excel, dat een voorafgaande = gebruikt om een expressie aan een cel te binden.
  • Hiermee wordt effectief ontkomen aan de syntaxis van de formuletaal, zodat YAML het niet probeert te parseren. Normaal gesproken zou YAML text: 1:00 behandelen als minuten en seconden en omzetten in een getal. Door een = in te voegen, zal YAML de impliciete typeregels niet gebruiken en formules zullen niet nadelig worden beïnvloed. Gebruik maken van = dekt de meeste gevallen, maar niet alle, en die uitzonderingen worden beschreven in de volgende sectie, Formules met één regel.
  • In de toekomst zullen we beide formules ondersteunen (begint met =) en niet-formules (geen =) in hetzelfde bestand, net zoals in Excel. We kunnen dit doen in YAML- en niet-YAML-bestanden in alle Microsoft Power Platform-bronbestanden. Overal waar een formule wordt ondersteund, onderscheidt een voorafgaand = een Power Apps-formule van een statische scalaire waarde.

Formules met één regel

Formules met één regel worden in de volgende vorm geschreven:

Naam:SPACE=Expressie

De spatie tussen de dubbele punt en het gelijkteken is vereist om YAML-compatibel te zijn. Het gelijkteken verstoort de normale interpretatie van de expressie door YAML, waardoor de rest van de regel kan worden geïnterpreteerd als Power Fx. Bijvoorbeeld: 

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

Het hekje # en de dubbele punt : zijn nergens toegestaan in formules met één regel, zelfs niet als ze in een tekenreeks tussen aanhalingstekens of identifier-naam staan. Als u een hekje of dubbele punt wilt gebruiken, moet u de formule uitdrukken als een formule met meerdere regels. Het hekje wordt geïnterpreteerd als een opmerking in YAML en de dubbele punt wordt geïnterpreteerd als een nieuwe naamtoewijzing in YAML. Om een opmerking toe te voegen aan een opmerking van één regel, gebruikt u het Power Fx-regelcommentaar dat begint met //.

Het gebruik van normale YAML-escaping met enkele aanhalingstekens en C-achtige backslashes wordt niet ondersteund; gebruik in plaats daarvan een formule met meerdere regels. Dit is ten behoeve van de consistentie en om knippen/plakken tussen de formulebalk in Power Apps Studio en YAML-bronbestanden te vergemakkelijken.

Bekijk documentatie voor operators en id's in canvas-apps voor details over toegestane namen en de structuur van een expressie.

Formules met meerdere regels

Formules kunnen meerdere regels beslaan met behulp van YAML's scalaire blokindicatoren:

Naam:SPACE ( | of |+ of |- ) =ExpressieregelExpressieregel ...

Alle regels die deel uitmaken van het blok, moeten ten minste één spatie vanaf het niveau van de eerste regel inspringen.

Bijvoorbeeld: 

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

Alle vormen van meerregelige scalaire YAML-notaties worden geaccepteerd bij het importeren, inclusief, bijvoorbeeld, >+. Om ervoor te zorgen dat de witruimte correct wordt bewaard, worden alleen |, |+, of |- geproduceerd.

Componentexemplaar

Componenten worden als exemplaren herkend met behulp van de YAML-objectnotatie. Het type object wordt bepaald met de As-operator als onderdeel van de YAML-tag aan de linkerkant. Voor containerbesturingselementen kunnen objecten worden genest.

NaamAsOnderdeeltype [ .Onderdeelsjabloon ] : ( Formule-één-regel of Formule-meerdere-regels of Objectexemplaar ) ...

Alle regels die deel uitmaken van het blok, moeten ten minste één spatie vanaf het niveau van de eerste regel inspringen.

Bijvoorbeeld: 

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
            )

Onderdeeltype kan elk canvasonderdeel of elk besturingselement zijn. Basistypen, zoals Aantal, worden niet ondersteund.

Onderdeelsjabloon is een optionele specificatie voor onderdelen die verschillende sjablonen hebben, zoals de Galerie. Niet alle componenten hebben sjablonen.

Als Naam speciale tekens bevat en tussen enkele aanhalingstekens staat, is escaping nodig van de hele zin links van de dubbele punt. Dit kan op twee manieren:

  • Gebruik enkele aanhalingstekens om de hele linkerkant te omgeven, waarbij de bestaande enkele aanhalingstekens moeten worden verdubbeld: 
    '''A name with a space'' As Gallery':
  • Gebruik dubbele aanhalingstekens om de hele linkerkant te omgeven, maar pas op dat er geen dubbele aanhalingstekens in de naam staan: 
    "'A name with a space' As Gallery":

Definitie van component

Evenzo worden componenten gedefinieerd door een exemplaar van een van de ondersteunde basistypen te maken. De basistypen kunnen niet rechtstreeks als exemplaren worden toegepast. Binnen een objectdefinitie kunnen eigenschappen worden toegevoegd aan het basistype.

De ondersteunde basetypen zijn: CanvasComponent

Eenvoudige definitie van eigenschappen

Componenten gebruiken eigenschappen om te communiceren met de app waarin ze worden gehost.

Naam: ( Expressie-één-regel of Expressie-meerdere-regels )

Het type formule wordt geïmpliceerd door het type expressie.

Voor invoereigenschappen biedt de expressie de standaard die in de app moet worden ingevoegd wanneer de component wordt toegepast. De maker kan deze expressie naar eigen inzicht wijzigen, maar kan het type niet wijzigen.

Voor uitvoereigenschappen geeft de expressie de uit te voeren berekening. De maker kan deze expressie niet wijzigen, deze is ingekapseld in de component.

Op dit moment zijn alle eigenschappen alleen gegevensstromen en kunnen ze geen bijwerkingen bevatten.

Op dit moment worden aanvullende metagegevens over de eigenschap hier niet gedefinieerd, maar in de andere bestanden van het .msapp-bestand, bijvoorbeeld de beschrijving van de eigenschap.

Bijvoorbeeld: 

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-compatibiliteit

YAML-commentaar

YAML-regelcommentaar gescheiden door het hekje # wordt nergens in de bronfindeling bewaard. Gebruik in plaats daarvan voor de scheiding van het regelcommentaar //-tekens of blokkeer commentaar met /* en */. Meer informatie: Commentaar

Fouten door veelvoorkomende valkuilen

Er zijn een paar plaatsen waar de grammatica's van Power Fx en van YAML incompatibel zijn of verwarrend kunnen zijn voor een gebruiker. In deze gevallen wordt er een fout gegenereerd.

Zoals in het volgende voorbeeld:

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

Het hekje # wordt door YAML als commentaar behandeld, ook al is het ingesloten in wat Excel beschouwt als een tekstreeks (omsloten door dubbele aanhalingstekens). Om verwarring te voorkomen, wordt in deze gevallen een foutmelding getoond tijdens het importeren. In deze gevallen kan in plaats daarvan een YAML-formulier met meerdere regels worden gebruikt.

In het geval van de waarde voor record, beschouwt YAML a: en b: als een andere binding voor de naamstoewijzing. Met YAML kan dezelfde naamstoewijzing worden hergebruikt, waarbij de laatste stilzwijgend alle eerdere definities overschrijft. Omdat dit voor een low-code maker verwarrend kan zijn en kan resulteren in het verlies van een eigenschapsformule, wordt er een fout gegenereerd als dezelfde naam twee keer wordt aangetroffen.