Power FxGramática de fórmulas YAML

Nota

Microsoft Power Fx es el nuevo nombre del lenguaje de fórmulas para aplicaciones de lienzo. Estos artículos son un trabajo en progreso a medida que extraemos el idioma de las aplicaciones de lienzo, lo integramos con otros productos Microsoft Power Platform y ponerlo a disposición como código abierto. Empiece con Información general de Microsoft Power Fx para una introducción al idioma.

Microsoft Power Fx tiene una gramática bien establecida para expresiones basadas en Excel. Sin embargo, cuando se utiliza en Power Apps y otros anfitriones donde la interfaz de usuario proporciona el enlace de nombre a expresión para una fórmula, no existe una forma estándar de editar el enlace de la fórmula como texto.

Hemos seleccionado el estándar de la industria YAML como nuestro lenguaje para esta vinculación. Ya existe una gran cantidad de editores, herramientas y bibliotecas para trabajar con YAML. Este artículo describe cómo representamos fórmulas en YAML.

En este momento, solo admitimos un subconjunto restringido de YAML. Solo se admiten las construcciones descritas en este artículo.

No todo lo que define una aplicación de lienzo se representa aquí; la información adicional fluye a través de otros archivos que la herramienta produce y consume.

Primer signo igual

En primer lugar, todas las expresiones deben comenzar con un signo igual inicial =:

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

Usamos el = de esta manera por tres razones:

• Es coherente con Excel, que utiliza = al principio para unir una expresión a una celda.
• De hecho, escapa a la sintaxis del lenguaje de fórmulas para que YAML no intente analizarlo. Normalmente, YAML trataría text: 1:00 como minutos y segundos, convirtiéndolo en un número. Insertando un =, YAML no utilizará sus reglas de escritura implícitas y las fórmulas no se verán dañadas. El uso de = cubre la mayoría de los casos, pero no todos, y esas excepciones se describen en la siguiente sección, Fórmulas de una sola línea.
• En el futuro, admitiremos ambas fórmulas (comienza con =) y no fórmulas (no =) en el mismo archivo, tal como lo hace Excel. Podemos hacer esto en archivos YAML y no YAML por igual en archivos fuente de Microsoft Power Platform. En cualquier lugar donde se admita una fórmula, el interlineado = diferencia una expresión de fórmula de Power Apps a partir de un valor escalar estático.

Fórmulas de línea única

Las fórmulas de una sola línea se escriben en la forma:

Nombre:SPACE=Expresión

El espacio entre los dos puntos y el signo igual debe ser compatible con YAML. El signo igual interrumpe la interpretación normal de YAML de la expresión, lo que permite que el resto de la línea se interprete como Power Fx. Por ejemplo:

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

El signo de número # y los dos puntos : no se permiten en ninguna parte de las fórmulas de una sola línea, incluso si están en una cadena de texto entre comillas o en un nombre de identificador. Para usar un signo numérico o dos puntos, debe expresar la fórmula como una fórmula de varias líneas. El signo de número se interpreta como un comentario en YAML y los dos puntos se interpretan como un nuevo mapa de nombre en YAML. Para agregar un comentario a un comentario de una sola línea, use el comentario de línea de Power Fx que comienza con //.

No se admite el uso de escape YAML normal con comillas simples y barras invertidas tipo C; en su lugar, utilice una fórmula de varias líneas. Esto es por consistencia y para facilitar cortar / pegar entre la barra de fórmulas en Power Apps Studio y archivos fuente YAML.

Vea la documentación de las aplicaciones de lienzo operadores e identificadores para obtener detalles sobre los nombres permitidos y la estructura de una expresión.

Fórmulas multilínea

Las fórmulas pueden abarcar varias líneas mediante el uso de indicadores escalares de bloque de YAML:

Nombre:SPACE ( | o |+ o |- ) =Expression-LineExpression-Line ...

Todas las líneas que forman parte del bloque deben tener una sangría de al menos un espacio desde el nivel de la primera línea.

Por ejemplo:

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

Todas las formas de notaciones escalares multilínea YAML se aceptan en la importación, incluso >+, por ejemplo. Sin embargo, para garantizar que los espacios en blanco se conserven correctamente, solo se producen |, |+ o |-.

Instancia de componente

Los componentes se instancian mediante la notación de objetos YAML. El tipo de objeto se establece con el operador As como parte de la etiqueta YAML del lado izquierdo. Para los controles de contenedor, los objetos se pueden anidar.

NombreAsComponent-Type [ .Component-Template ] : ( Single-Line-Formula o Multi-Line-Formula o Object-instance ) ...

Todas las líneas que forman parte del bloque deben tener una sangría de al menos un espacio desde el nivel de la primera línea.

Por ejemplo:

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 puede ser cualquier componente o control del lienzo. Tipos de base, como Número, no son compatibles.

Component-Template es un especificador opcional para componentes que tienen diferentes plantillas, como la Galería. No todos los componentes tienen plantillas.

Si Nombre contiene caracteres especiales y está encapsulado con comillas simples, deberá escapar toda la frase al lado izquierdo de los dos puntos. Esta especificación se puede hacer de una de las siguientes formas:

• Utilice comillas simples para envolver todo el lado izquierdo, lo que requiere que las comillas simples existentes se utilicen dos veces:

  '''A name with a space'' As Gallery':
  

• Use comillas dobles para envolver todo el lado izquierdo, pero asegúrese de que no haya comillas dobles en el nombre:

  "'A name with a space' As Gallery":
  

Definición del componente

De manera similar, los componentes se definen creando una instancia de uno de los tipos base admitidos. Los tipos base no se pueden instanciar directamente. Dentro de una definición de objeto, se pueden agregar propiedades a lo que proporciona el tipo base.

Los tipos base admitidos son: CanvasComponent

Definición de propiedad sencilla

Los componentes usan propiedades para comunicarse con la aplicación en la que están alojados.

Nombre: ( Single-Line-Expression o Multi-Line-Expression )

El tipo de fórmula está implícito en el tipo de expresión.

Para las propiedades de entrada, la expresión proporciona el valor predeterminado que se insertará en la aplicación cuando se instancia el componente. El creador puede modificar esta expresión como mejor le parezca, pero no puede cambiar el tipo.

Para las propiedades de salida, la expresión proporciona el cálculo a realizar. El creador no puede modificar esta expresión, está encapsulada en el componente.

En este momento, todas las propiedades son solo flujo de datos y no pueden contener efectos secundarios.

En este momento, los metadatos adicionales sobre la propiedad no se definen aquí, sino que se definen en los otros archivos del archivo .msapp, por ejemplo, la descripción de la propiedad.

Por ejemplo:

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

Compatibilidad YAML

Comentarios YAML

Comentarios de la línea YAML delimitados por el signo de número # no se conservan en ninguna parte del formato de origen. En su lugar, dentro de una fórmula, delimite los comentarios de línea con caracteres // o bloquear comentarios con /* y */. Más información: Comentarios

Errores por trampas comunes

Hay algunos lugares donde las gramáticas de Power Fx y YAML son incompatibles o pueden resultar confusas para el usuario. En estos casos, se arroja un error.

Por ejemplo, a continuación:

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

YAML trata el signo de número # como un comentario, aunque está incrustado en lo que Excel considera una cadena de texto (entre comillas dobles). Para evitar confusiones, este caso arrojará un error durante la importación. En su lugar, se puede utilizar un formulario de varias líneas YAML.

En el caso del valor de record, YAML considera a: y b: para ser otro enlace de mapa de nombres. YAML permite reutilizar el mismo mapa de nombre, y el último anula silenciosamente cualquier definición anterior. Debido a que esto puede ser confuso para un creador de código bajo y puede resultar en la pérdida de una fórmula de propiedad, se genera un error si se encuentra el mismo nombre dos veces.