Gramática da fórmula YAML do Power Fx
Nota
Microsoft Power Fx é o novo nome para a linguagem de fórmulas para aplicações de tela. Estes artigos associados são um trabalho em curso à medida que extraímos o idioma das aplicações de tela, o integramos com outros produtos do Microsoft Power Platform e o disponibilizamos como open source. Comece com a Descrição geral de Microsoft Power Fx para uma introdução ao idioma.
O Microsoft Power Fx tem uma gramática bem estabelecida para expressões baseadas no Excel. No entanto, quando utilizados no Power Apps e noutros anfitriões onde a IU fornece o enlace nome-a-expressão para uma fórmula, não existe uma forma padrão de editar o enlace da fórmula como texto.
Selecionámos o padrão da indústria YAML como nossa linguagem para este enlace. Já existe um grande número de editores, ferramentas e bibliotecas para trabalhar com YAML. Este artigo descreve como representamos fórmulas no YAML.
Neste momento, suportamos apenas um subconjunto restrito de YAML. Apenas as construções descritas neste artigo são suportadas.
Nem tudo o que define uma aplicação de tela está representado aqui; informação adicional flui através de outros ficheiros que a ferramenta produz e consome.
Sinal de igualdade à esquerda
Em primeiro lugar, todas as expressões têm de começar por um sinal de igualdade à esquerda =
:
Visible: =true
X: =34
Text: |
="Hello, " &
"World"
Utilizamos =
desta forma por três razões:
- É consistente com o Excel, que utiliza um
=
à esquerda para vincular uma expressão a uma célula. - Insere caracteres de escape na sintaxe da linguagem da fórmula para esse YAML não tentar analisá-la. Normalmente, a YAML trataria
text: 1:00
como minutos e segundos, convertendo-os num número. Ao inserir um=
, a YAML não utilizará as respetivas fórmulas e regras de escrita implícitas não serão danificadas. A utilização de=
cobre mais casos, mas não todos, e essas exceções são descritas na seguinte secção, Fórmulas de linha única. - No futuro, vamos suportar as duas fórmulas (começa por
=
) e não fórmulas (não=
) no mesmo ficheiro, tal como o Excel faz. Podemos fazer isto em ficheiros YAML e não YAML em ficheiros de origem do Microsoft Power Platform. Em qualquer lugar que uma fórmula é suportada, o=
à esquerda diferencia uma expressão de fórmula do Power Apps de um valor escalar estático.
Fórmulas de linha única
As fórmulas de linha única são escritas no formulário:
Expressão do nome:
SPACE
=
O espaço entre os dois pontos e o sinal de igual é necessário para ser compatível com a YAML. O sinal de igual interrompe a interpretação normal da YAML da expressão, o que permite interpretar o resto da linha como Power Fx. Por exemplo:
Text1: ="Hello, World"
Text2: ="Hello " & ", " & "World"
Number1: =34
Boolean1: =true
Time1: =1:34
O sinal de número #
e os dois pontos :
não são permitidos em nenhuma lugar das fórmulas de uma linha, mesmo que estejam numa cadeia de texto ou nome de identificador entre aspas. Para utilizar um sinal de número ou dois pontos, tem de expressar a fórmula como uma fórmula de várias linhas. O sinal de número é interpretado como um comentário na YAML e os dois pontos são interpretados como um novo mapa de nome na YAML. Para adicionar um comentário a um comentário de uma única linha, utilize o comentário da linha do Power Fx a começar com //
.
A utilização de caracteres de escape normais da YAML com plicas e barras invertidas tipo C não é suportada; utilize antes uma fórmula de várias linhas. Isto é feito por motivos de consistência e para facilitar a ação de cortar/colar entre a barra de fórmulas no Power Apps Studio e os ficheiros de origem da YAML.
Consulte os operadores e identificadores de aplicações de tela e a documentação para obter detalhes sobre nomes permitidos e a estrutura de uma expressão.
Fórmulas de várias linhas
As fórmulas podem abranger várias linhas ao utilizar indicadores escalares de bloco da YAML:
Nome:
SPACE
( |
ou |+
|-
) =
Linha de Expressão-Linha-Expressão ...
Todas as linhas que fazem parte do bloco devem conter avanço de, pelo menos, um espaço a partir do nível da primeira linha.
Por exemplo:
Text1: |
="Hello, World"
Text2: |
="Hello" &
"," &
"World"
Todas as formas de notações escalares de várias linhas da YAML são aceites durante a importação, incluindo >+
, por exemplo. No entanto, para garantir que o espaço em branco é devidamente preservado, só são produzidos |
, |+
ou |-
.
Instância de componente
Os componentes são instanciados através da notação de objetos YAML. O tipo de objeto é estabelecido com o operador As
como parte da tag YAML do lado esquerdo. Para controlos de recipientes, os objetos podem ser aninhados.
NomeAs
Component-Type [ .
Component-Template ] :
( Single-Line-Formula ou Multi-Line-Formula ou Object-instance ) ...
Todas as linhas que fazem parte do bloco devem conter avanço de, pelo menos, um espaço a partir do nível da primeira linha.
Por exemplo:
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 pode ser qualquer componente de tela ou controle. Não são suportados tipos de base, tais como Número.
Component-Template é um especificador opcional para componentes que têm modelos diferentes, como a Galeria. Nem todos os componentes têm modelos.
Se Nome contiver caracteres especiais e estiver entre plicas, toda a expressão à esquerda dos dois pontos terá de estar entre caracteres de escape. Isto pode ser feito numa das seguintes formas:
- Utilize plicas para encapsular todo o lado esquerdo, o que exige que as plicas existentes sejam usadas duas vezes:
'''A name with a space'' As Gallery':
- Utilize aspas para encapsular todo o lado esquerdo, mas certifique-se de que não existem aspas no nome:
"'A name with a space' As Gallery":
Definição do componente
Da mesma forma, os componentes são definidos ao criar uma instância de um dos tipos de base suportados. Os tipos de base não podem ser instanciados diretamente. Dentro de uma definição de objeto, as propriedades podem ser adicionadas ao que o tipo de base fornece.
Os tipos de base suportados são: CanvasComponent
Definição de propriedade simples
Os componentes utilizam propriedades para comunicar com a aplicação em que estão alojados.
Nome:
( Expressão de linha única ou Expressão de várias linhas)
O tipo de fórmula é implícito pelo tipo de expressão.
Para as propriedades de entrada, a expressão fornece a predefinição a ser inserida na aplicação quando o componente é formatado como instância. O criador pode modificar esta expressão conforme entender, mas não pode alterar o tipo.
Para as propriedades de saída, a expressão fornece o cálculo a ser realizado. O criador não pode modificar esta expressão, está encapsulada no componente.
Neste momento, todas as propriedades são apenas do fluxo de dados e não podem conter efeitos colaterais.
Neste momento, os metadados adicionais sobre a propriedade não são definidos aqui, mas são definidos nos outros ficheiros do ficheiro .msapp
, por exemplo, na descrição da propriedade.
Por exemplo:
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
Compatibilidade do YAML
Comentários do YAML
Os comentários da linha do YAML delimitados pelo sinal de número #
não são preservados em qualquer lugar no formato de origem. Em vez disso, dentro de uma fórmula, delimite os comentários de linha com carateres //
ou comentários de bloco com /*
e */
. Mais informações: Comentários
Erros para lapsos comuns
Existem alguns lugares onde as gramáticas do Power Fx e do YAML são incompatíveis ou podem ser confusas para um utilizador. Nestes casos, é gerado um erro.
Por exemplo, no seguinte:
Text: ="Hello #PowerApps"
Record: ={ a: 1, b: 2 }
o sinal de número #
é tratado como um comentário pela YAML, mesmo estando incorporado naquilo que o Excel considera ser uma cadeia de texto (delimitada por aspas). Para evitar confusão, este caso gera um erro durante a importação. Em vez disso, pode utilizar o formato de várias linhas da YAML.
No caso do valor para record
, a YAML considera a:
e b:
como outro enlace de mapa de nome. A YAML permite que o mesmo mapa de nomes seja reutilizado, com o último a substituir de forma silenciosa quaisquer definições anteriores. Como isto pode ser confuso para um criador de pouco código e pode resultar na perda de uma fórmula de propriedade, é gerado um erro se o mesmo nome for encontrado duas vezes.