Power FxGrammaire des formules YAML

  • Article

Note

Microsoft Power Fx est le nouveau nom du langage de formule pour les applications de canevas. Ces articles associés sont un travail en cours car nous extrayons le langage des applications de canevas, l’intégrons à d’autres produits Microsoft Power Platform, et le rendons disponible en open source. Commencez par l’Aperçu de Microsoft Power Fx pour une introduction à la langue.

Microsoft Power Fx a une grammaire bien établie pour les expressions basées sur Excel. Cependant, lorsqu’il est utilisé dans Power Apps et d’autres hôtes où l’interface utilisateur fournit une liaison nom-expression pour une formule, il n’existe aucun moyen standard de modifier la liaison de formule sous forme de texte.

Nous avons sélectionné la norme de l’industrie YAML comme notre langue pour cette liaison. Il existe déjà un grand nombre d’éditeurs, d’outils et de bibliothèques pour travailler avec YAML. Cet article décrit comment nous représentons les formules dans YAML.

Pour le moment, nous ne prenons en charge qu’un sous-ensemble restreint de YAML. Seules les constructions décrites dans cet article sont prises en charge.

Tout ce qui définit une application canevas n’est pas représenté ici ; des informations supplémentaires circulent dans d’autres fichiers que l’outil produit et consomme.

Premier signe égal

Tout d’abord, toutes les expressions doivent commencer par un signe égal de premier plan =:

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

Nous utilisons le signe = de cette manière pour trois raisons :

  • Il est cohérent avec Excel qui utilise un interligne = pour lier une expression à une cellule.
  • Il échappe efficacement à la syntaxe du langage de formule afin que YAML ne tente pas de l’analyser. Normalement, YAML traiterait text: 1:00 en minutes et en secondes, en le convertissant en nombre. En insérant un =, YAML n’utilisera pas ses règles de typage implicites et les formules ne seront pas affectées. L’utilisation de = couvre la plupart des cas, mais pas tous, et ces exceptions sont décrites dans la section suivante, Formules sur une seule ligne.
  • À l’avenir, nous prendrons en charge les deux formules (commence par =) et les non-formules (non =) dans le même fichier, tout comme le fait Excel. Nous pouvons le faire dans les fichiers YAML et non-YAML de la même manière dans les fichiers source Microsoft Power Platform. Partout où une formule est prise en charge, le signe = en tête différencie une expression de formule Power Apps d’une valeur scalaire statique.

Formules sur une seule ligne

Les formules sur une seule ligne sont écrites sous la forme :

Nom:SPACE=Expression

L’espace entre les deux points et le signe égal doit être conforme à YAML. Le signe égal perturbe l’interprétation normale de l’expression par YAML, permettant au reste de la ligne d’être interprété comme Power Fx. Par exemple : 

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

Le signe dièse # et les deux-points : ne sont autorisés nulle part dans les formules sur une seule ligne, même si ils se trouvent dans une chaîne de texte ou un nom d’identifiant entre guillemets. Pour utiliser un signe dièse ou deux-points, vous devez exprimer la formule en tant que formule multiligne. Le signe dièse est interprété comme un commentaire en YAML et les deux points sont interprétés comme une nouvelle carte de nom en YAML. Pour ajouter un commentaire à un commentaire sur une seule ligne, utilisez le commentaire de ligne Power Fx commençant par //.

L’utilisation de l’échappement YAML normal avec des guillemets simples et des barres obliques inverses de type C n’est pas prise en charge ; utilisez plutôt une formule multiligne. Ceci est pour la cohérence et pour faciliter le copier/coller entre la barre de formule dans Power Apps Studio et les fichiers source YAML.

Reportez-vous à la documentation sur les opérateurs et identificateurs des applications canevas pour plus de détails sur les noms autorisés et la structure d’une expression.

Formules multilignes

Les formules peuvent s’étendre sur plusieurs lignes en utilisant les indicateurs scalaires de bloc de YAML :

Nom:SPACE ( | ou |+ ou |- ) =Ligne d’expressionLigne d’expression ...

Toutes les lignes qui font partie du bloc doivent être en retrait d’au moins un espace à partir du niveau de la première ligne.

Par exemple : 

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

Toutes les formes de notations scalaires multilignes YAML sont acceptées à l’importation, y compris >+, par exemple. Cependant, pour garantir que les espaces blancs sont correctement préservés |, |+ ou |- sont produits.

Instance de composant

Les composants sont instanciés à l’aide de la notation d’objet YAML. Le type de l’objet est établi avec l’opérateur As dans le cadre de la balise YAML du côté gauche. Pour les contrôles de conteneur, les objets peuvent être imbriqués.

NomAsType de composant [ .Modèle de composant ] : ( Formule sur une seule ligne ou Formule sur plusieurs lignes ou Instance d’objet ) ...

Toutes les lignes qui font partie du bloc doivent être en retrait d’au moins un espace à partir du niveau de la première ligne.

Par exemple :

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
            )

Type de composant peut être n’importe quel composant ou contrôle du canevas. Les types de base, tels que Nombre, ne sont pas pris en charge.

Modèle de composant est un spécificateur facultatif pour les composants qui ont différents modèles, tels que la Galerie. Tous les composants n’ont pas de modèles.

Si Nom contient des caractères spéciaux et est incluse dans un wrapper avec des guillemets simples, la phrase entière à gauche des deux points devra être échappée. Cela peut être effectué dans les emplacements suivants :

  • Utilisez des guillemets simples pour englober tout le côté gauche, ce qui nécessite que les guillemets simples existants soient utilisés deux fois : 
    '''A name with a space'' As Gallery':
  • Utilisez des guillemets doubles pour englober tout le côté gauche, mais assurez-vous qu’il n’y a pas de guillemets doubles dans le nom : 
    "'A name with a space' As Gallery":

Définition du composant

De même, les composants sont définis en créant une instance de l’un des types de base pris en charge. Les types de base ne peuvent pas être instanciés directement. Dans une définition d’objet, des propriétés peuvent être ajoutées à ce que le type de base fournit.

Les types de base pris en charge sont : CanvasComponent

Définition de propriété simple

Les composants utilisent des propriétés pour communiquer avec l’application dans laquelle ils sont hébergés.

Nom: ( Expression sur une seule ligne ou Expression sur plusieurs lignes )

Le type de la formule est impliqué par le type de l’expression.

Pour les propriétés d’entrée, l’expression fournit la valeur par défaut à insérer dans l’application lorsque le composant est instancié. Le créateur peut modifier cette expression comme bon lui semble, mais ne peut pas changer le type.

Pour les propriétés de sortie, l’expression fournit le calcul à effectuer. Le créateur ne peut pas modifier cette expression, elle est encapsulée dans le composant.

Pour le moment, toutes les propriétés sont uniquement des flux de données et ne peuvent pas contenir d’effets secondaires.

Pour le moment, les métadonnées supplémentaires relatives à la propriété ne sont pas définies ici mais sont à la place définies dans les autres fichiers du fichier .msapp, par exemple la description de la propriété.

Par exemple : 

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

Commentaires YAML

Commentaires de ligne YAML délimités par le signe dièse # ne sont conservés nulle part dans le format source. Au lieu de cela, dans une formule, délimitez les commentaires de ligne avec // caractères ou bloquer les commentaires avec /* et */. Plus d’informations : Commentaires

Erreurs et pièges courants

Il existe quelques endroits où les grammaires Power Fx et YAML sont incompatibles ou peuvent prêter à confusion pour un utilisateur. Dans ces cas, une erreur est générée.

Par exemple, dans ce qui suit :

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

Le signe dièse # est traité comme un commentaire par YAML, même s’il est intégré dans ce qu’Excel considère comme une chaîne de texte (inclus dans un wrapper avec des guillemets doubles). Pour éviter toute confusion, ce cas générera une erreur lors de l’importation. Un formulaire multiligne YAML peut être utilisé à la place.

Dans le cas de la valeur pour record, YAML considère a: et b: pour être une autre liaison de mappage de noms. YAML permet de réutiliser le même mappage de noms, le dernier remplaçant silencieusement toutes les définitions précédentes. Étant donné que cela peut être déroutant pour un créateur de code bas et peut entraîner la perte d’une formule de propriété, une erreur est générée si le même nom est rencontré deux fois.