Compartilhar via

Power FxGramática de fórmula YAML

  • Artigo

Observação

Microsoft Power Fx é o novo nome da linguagem de fórmula para aplicativos de tela. Esses artigos são um trabalho em andamento à medida que extraímos a linguagem de aplicativos de tela, integramos a linguagem a outros produtos do Microsoft Power Platform e disponibilizamo-na como software livre. Comece com o artigo Visão geral do Microsoft Power Fx para ver uma introdução à linguagem.

O Microsoft Power Fx tem uma gramática bem estabelecida para expressões baseadas no Excel. No entanto, quando usado no Power Apps e outros hosts em que a interface do usuário fornece a associação de nome para expressão a uma fórmula, não existe uma maneira padrão de editar a associação de fórmula como texto.

Selecionamos o YAML padrão da indústria como nossa linguagem para esta associação. Já existe um grande número de editores, ferramentas e bibliotecas para trabalhar com YAML. Este artigo descreve como representamos fórmulas em YAML.

No momento, oferecemos suporte apenas a um subconjunto restrito de YAML. Apenas os construtos descritos neste artigo têm suporte.

Nem tudo que define um aplicativo de tela está representado aqui; outras informações navegam por outros arquivos que a ferramenta produz e consome.

Sinal de igualdade inicial

Em primeiro lugar, todas as expressões devem começar com um sinal de igualdade =:

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

Nós usamos o = desta maneira por três razões:

  • O processo é consistente com o Excel, que usa um o sinal = inicial para associar uma expressão a uma célula.
  • Ele consegue escapar da sintaxe da linguagem de fórmula para que a YAML não tente analisá-la. Normalmente, a YAML trataria text: 1:00 como minutos e segundos, convertendo-o em um número. Ao inserir um sinal =, a YAML não usará suas regras de digitação implícitas e as fórmulas não serão prejudicadas. O uso do sinal = se encaixa na maioria dos casos, mas não em todos, e essas exceções estão descritas nesta seção, Fórmulas de linha única.
  • No futuro, ofereceremos suporte para as duas fórmulas (que começam com =) e não fórmulas (que não têm =) no mesmo arquivo, assim como o Excel faz. Podemos fazer isso em arquivos YAML e não YAML em arquivos de origem do Microsoft Power Platform. Em qualquer lugar onde uma fórmula tenha suporte, 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 formato:

Nome:SPACE=Expressão

O espaço entre os dois pontos e o sinal de igualdade deve estar em conformidade com a YAML. O sinal de igualdade interrompe a interpretação normal de YAML da expressão, permitindo que o resto da linha seja interpretado como Power Fx. Por exemplo: 

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

O sinal numérico # e os dois pontos : não são permitidos em qualquer lugar na fórmulas de linha única, mesmo se estiverem em uma cadeia de caracteres entre aspas ou em um nome de identificador. Para usar um sinal numérico ou dois pontos, você deve expressar a fórmula como uma fórmula de várias linhas. O sinal numérico é interpretado como um comentário em YAML, e os dois pontos são interpretados como um novo mapa de nome em YAML. Para adicionar um comentário a um comentário de linha única, use o comentário de linha do Power Fx começando com //.

Não é possível usar o escape normal da YAML com aspas simples e barras invertidas do tipo C; em vez disso, use uma fórmula de várias linhas. Isso é feito para manter consistência e facilitar o recorte/cola entre a barra de fórmula no Power Apps Studio e os arquivos de origem YAML.

Veja a documentação de operadores e identificadores de aplicativos de tela para ver detalhes sobre os nomes permitidos e a estrutura de uma expressão.

Fórmulas de várias linhas

As fórmulas podem abranger várias linhas usando os indicadores escalares de bloco da YAML:

Nome:SPACE ( | ou |+ ou |- ) =Linha de expressãoLinha de expressão ...

Todas as linhas que fazem parte do bloco devem ser recuadas 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 aceitas na importação, incluindo >+, por exemplo. No entanto, para garantir que o espaço em branco seja mantido de forma adequada, apenas |, |+ ou |- são produzidos.

Instância de componente

Os componentes são instanciados usando-se a notação de objeto da YAML. O tipo de objeto é estabelecido com o operador As como parte da marcação da YAML do lado esquerdo. Para controles de contêiner, os objetos podem ser aninhados.

NomeAsTipo-de-componente [ .Modelo-de-componente ] : ( Fórmula-de-linha-única ou Fórmula-de-várias-linhas ou Instância-de-objeto ) ...

Todas as linhas que fazem parte do bloco devem ser recuadas 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 ou controle do canvas. Tipos de base, como Número, não são compatíveis.

Component-Template é um especificador opcional para componentes que têm modelos diferentes, como a Galeria. Nem todos os componentes possuem modelos.

Se Nome contém caracteres especiais e é delimitado por aspas simples, a frase inteira à esquerda dos dois pontos precisará ter escape. Isso precisa ser feito de uma destas formas:

  • Use aspas simples para envolver todo o lado esquerdo, o que requer que as aspas simples existentes sejam usadas duas vezes: 
    '''A name with a space'' As Gallery':
  • Use aspas duplas para envolver todo o lado esquerdo, mas certifique-se de que não haja aspas duplas no nome: 
    "'A name with a space' As Gallery":

Definição do componente

Os componentes também são definidos criando uma instância de um dos tipos de base compatíveis. Os tipos básicos 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 compatíveis são: CanvasComponent

Definição de propriedade simples

Os componentes usam propriedades para se comunicar com o aplicativo no qual estão hospedados.

Nome: ( Expressão de uma única linha ou Expressão de várias linhas )

O tipo da fórmula está implícito no tipo da expressão.

Para propriedades de entrada, a expressão fornece o padrão a ser inserido no aplicativo quando o componente é instanciado. O criador pode modificar a expressão como achar adequado, mas não pode alterar o tipo.

Para propriedades de saída, a expressão fornece o cálculo a ser executado. O criador não pode modificar a expressão, pois ela está encapsulada no componente.

No momento, todas as propriedades são apenas para fluxo de dados e não podem conter efeitos colaterais.

No momento, outros metadados sobre a propriedade não estão definidos aqui, mas nos outros arquivos do arquivo .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

Comentários de linha da YAML delimitados pelo sinal numérico # não são preservados no formato de origem. Em vez disso, dentro de uma fórmula, delimite os comentários de linha com caracteres // ou bloqueie comentários com /* e */. Mais informações: Comentários

Erros para armadilhas comuns

Existem alguns lugares onde as gramáticas Power Fx e YAML são incompatíveis ou podem ser confusas para o usuário. Nesses casos, ocorre um erro.

Por exemplo:

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

O sinal numérico # é tratado como um comentário pela YAML, embora esteja incorporado no que o Excel considera uma cadeia de caracteres (entre aspas duplas). Para evitar confusão, este caso gerará um erro durante a importação. Um formulário de várias linhas da YAML pode ser usado em seu lugar.

No caso do valor para record, a YAML considera a: e b: para ser outra associação de mapa de nomes. A YAML permite que o mesmo mapa de nomes seja reutilizado, com o último substituindo todas as definições anteriores. Como isso pode ser confuso para um criador de pouco código e pode resultar na perda de uma fórmula de propriedade, um erro será gerado se o mesmo nome aparecer duas vezes.