Поделиться через

Power FxГрамматика формул YAML

  • Статья

Заметка

Microsoft Power Fx — это новое название языка формул для приложений на основе холста. Эти статьи находятся в стадии разработки, поскольку мы извлекаем язык из приложений на основе холста, интегрируем его с другими продуктами Microsoft Power Platform и делаем его доступным как открытый исходный код. Начнем с Обзор Microsoft Power Fx для введения в язык.

Microsoft Power Fx имеет устоявшуюся грамматику для выражений на основе Excel. Однако при использовании в Power Apps и других хостах, где пользовательский интерфейс обеспечивает привязку имени к выражению для формулы, нет стандартного способа редактирования привязки формулы как текста.

Мы выбрали отраслевой стандарт YAML как наш язык для этой привязки. Уже существует большое количество редакторов, инструментов и библиотек для работы с YAML. В этой статье описывается, как мы представляем формулы в YAML.

В настоящее время мы поддерживаем только ограниченное подмножество YAML. Поддерживаются только конструкции, описанные в этой статье.

Здесь представлено не все, что определяет приложение на основе холста; дополнительная информация проходит через другие файлы, которые инструмент создает и использует.

Знак равенства в начале

Прежде всего, все выражения должны начинаться с знака равенства в начале =:

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

Мы используем = таким образом по трем причинам:

  • Это согласуется с Excel, в котором используется = вначале для привязки выражения к ячейке.
  • Это эффективно экранирует синтаксис языка формул, чтобы YAML не пытался его проанализировать. Обычно YAML обрабатывает text: 1:00 как минуты и секунды, преобразуя их в число. Если вставить =, YAML не будет использовать свои правила неявной типизации, и формулы не пострадают. С использованием = охватывается большинство случаев, но не все, и эти исключения описаны в следующем разделе Однострочные формулы.
  • В будущем мы будем поддерживать обе формулы (начинается с =) и не формулы (без =) в одном и том же файле как и в Excel. Мы можем сделать это как в файлах YAML, так и в файлах, отличных от YAML, в разных исходных файлах Microsoft Power Platform. Везде, где поддерживается формула, ведущий знак = отличает выражение формулы Power Apps от статического скалярного значения.

Однострочные формулы

Однострочные формулы записываются в виде:

Имя:SPACE=Выражение

Пробел между двоеточием и знаком равенства требуется для соответствия YAML. Знак равенства нарушает обычную интерпретацию выражения YAML, позволяя интерпретировать остальную часть строки как Power Fx. Например: 

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

Знак номера # и двоеточие : не допускаются нигде в однострочных формулах, даже если они находятся в текстовой строке в кавычках или имени идентификатора. Чтобы использовать знак номера или двоеточие, вы должны выразить формулу как многострочную формулу. Знак номера интерпретируется как комментарий в YAML, а двоеточие интерпретируется как новое сопоставление имен в YAML. Чтобы добавить комментарий к однострочному комментарию, используйте строковый комментарий Power Fx., начинающийся с //.

Использование обычного экранирования YAML с помощью одинарных кавычек и обратных косых черт в стиле C не поддерживается; вместо этого используйте многострочную формулу. Это сделано для единообразия и для облегчения вырезания/вставки между строкой формул в Power Apps Studio и исходными файлами YAML.

См. документацию по операторам и идентификаторам приложений на основе холста для получения подробной информации о допустимых именах и структуре выражения.

Многострочные формулы

Формулы могут охватывать несколько строк с использованием блочных скалярных индикаторов YAML:

Имя:SPACE ( | или |+ или |- ) =Линия-выраженияЛиния-выражения ...

Все строки, входящие в состав блока, должны иметь отступ как минимум на один пробел от уровня первой строки.

Например: 

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

При импорте принимаются все многострочные скалярные формы YAML, включая >+, например. Однако, чтобы гарантировать, что пробелы сохранены должным образом, выполняются только |, |+ или |-.

Экземпляр компонента

Компоненты создаются с использованием объектной формы YAML. Тип объекта устанавливается с помощью оператора As как часть левого тега YAML. Для контейнерных элементов управления объекты могут быть вложенными.

ИмяAsТип-компонента [ .Шаблон-компонента ] : ( Однострочная-формула или Многострочная-формула или Экземпляр-объекта ) ...

Все строки, входящие в состав блока, должны иметь отступ как минимум на один пробел от уровня первой строки.

Например: 

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 может быть любым компонентом холста или элементом управления. Базовые типы, такие как Число, не поддерживаются.

Component-Template — необязательный спецификатор для компонентов, имеющих разные шаблоны, например, Галерея. Не все компоненты имеют шаблоны.

Если Имя содержит специальные символы и заключен в одинарные кавычки, вся фраза слева от двоеточия должна быть экранирована. Это можно сделать одним из следующих способов:

  • Используйте одинарные кавычки, чтобы заключить всю левую часть, что требует, чтобы существующие одинарные кавычки использовались дважды: 
    '''A name with a space'' As Gallery':
  • Используйте двойные кавычки, чтобы заключить всю левую часть, но убедитесь, что в имени нет двойных кавычек: 
    "'A name with a space' As Gallery":

Определение компонентов

Точно так же компоненты определяются путем создания экземпляра одного из поддерживаемых базовых типов. Базовые типы не могут быть созданы напрямую. В рамках определения объекта свойства могут быть добавлены к тому, что предоставляет базовый тип.

Поддерживаются следующие базовые типы: CanvasComponent

Определение простого свойства

Компоненты используют свойства для связи с приложением, в котором они размещены.

Имя: ( Однострочное выражение или Многострочное выражение )

Тип формулы определяется типом выражения.

Для входных свойств выражение предоставляет значение по умолчанию, которое будет вставлено в приложение при создании экземпляра компонента. Создатель может изменить это выражение по своему усмотрению, но не может изменить тип.

Для выходных свойств выражение обеспечивает вычисление, которое необходимо выполнить. Создатель не может изменить это выражение, оно инкапсулировано в компоненте.

В настоящее время все свойства являются только потоком данных и не могут содержать побочные эффекты.

В настоящее время дополнительные метаданные о свойстве здесь не определены, а определены в других файлах файла .msapp, например описание свойства.

Например: 

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

Комментарии YAML

Строчные комментарии YAML, разделенные знаком номера # нигде не сохраняются в исходном формате. Вместо этого в формуле разделите строчные комментарии с помощью символов // или заблокируйте комментарии с помощью /* и */. Больше информации: Комментарии

Ошибки для распространенных ошибок

Есть несколько мест, где грамматики Power Fx и YAML несовместимы или могут сбивать с толку пользователя. В этих случаях выдается ошибка.

Например, в следующем:

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

знак номера # считается комментарием в YAML, даже если он встроен в то, что Excel считает текстовой строкой (заключенная в двойные кавычки). Во избежание путаницы в этом случае при импорте будет выдана ошибка. Вместо этого можно использовать многострочную форму YAML.

В случае значения для record, YAML считает a: и b: другой привязкой к сопоставлению имен. YAML позволяет повторно использовать одно и то же сопоставление имен, причем последнее автоматически отменяет любые предыдущие определения. Поскольку это может сбить с толку создателя с малым объемом кода и привести к потере формулы свойства, возникает ошибка, если одно и то же имя встречается дважды.