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

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 лівого краю. Для елементів керування контейнером об'єкти можуть бути вкладені.

Ім’я Component-TypeAs[ Component-Template .] ( : Однорядкова формула або Multi-Line-формула або екземпляр-об’єкт ) ...

Усі рядки, які входить до блоку, мають бути з відступами принаймні на один інтервал від рівня першого рядка.

Наприклад:

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

Просте визначення властивостей

Компоненти використовують властивості для обміну даними з програмою, у якій їх розміщено.

name: ( однорядковий вираз або багаторядковий вираз )

Тип формули обумовлюється типом виразу.

Для вхідних властивостей виразом у програмі заповнюватимуться значення за замовчуванням у разі створення екземпляра компонента. Розробник програми може змінити цей вираз за розміром, але не може змінити його тип.

Для властивостей вихідних даних виразом забезпечується виконання обчислень. Розробник програми не може змінити цей вираз, його інкапсульовано в компонент.

На цей час усі властивості є лише потоком даних і не можуть містити побічні дії.

Наразі тут не визначено додаткові метадані про властивість, але натомість визначено в інших файлах .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 дає змогу повторно використовувати зіставлення з однаковими іменами, автоматично перевизначаючи всі попередні визначення. У разі появи однакового імені відображатиметься помилка, оскільки це може бути незрозумілим для розробників малокодових додатків і спричинити втрату формули властивостей.