Power Fx YAML 公式语法

项目
10/16/2024

备注

Microsoft Power Fx 是画布应用公式语言的新名称。当我们从画布应用中提取语言，将其与其他 Microsoft Power Platform 产品集成并使其作为开放源代码提供时，这些文章还在撰写。从 Microsoft Power Fx 概述开始，了解对此语言的介绍。

Microsoft Power Fx 对于基于 Excel 的表达式有完善的语法。但是，当在 Power Apps 和 UI 为公式提供名称到表达式绑定的其他主机中使用时，没有可以将公式绑定编辑为文本的标准方法。

我们选择了行业标准 YAML 作为此绑定的语言。已有许多编辑器、工具和库可用于 YAML。本文介绍了如何在 YAML 中表示公式。

目前，我们仅支持一部分受限的 YAML。仅支持本文中介绍的构造。

此处并未表示定义画布应用的所有内容；其他信息散布在工具生成和使用的其他文件中。

前导等号

首先，所有表达式必须以前导等号 = 开头：

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

出于以下三种原因，我们以这种方式使用 =：

这与 Excel 一致，使用前导 = 将表达式绑定到单元格。
它可以有效转义公式语言的语法，让 YAML 不会尝试分析它。通常，YAML 会将 text: 1:00 视为分钟和秒，将其转换为数字。通过插入 =，YAML 不会使用其隐式键入规则，公式不会被破坏。使用 = 涵盖大多数情况，但不是全部，例外在下一节单行公式中有述。
将来，我们将在同一文件中同时支持公式（以 = 开头）和非公式（没有 =），就像 Excel 一样。我们可以跨 Microsoft Power Platform 源文件在 YAML 和非 YAML 文件中均实现此目的。在支持公式的任何位置，前导 = 将从静态标量值中区分 Power Apps 公式表达式。

单行公式

采用以下形式编写单行公式：

名称:SPACE=表达式

冒号和等号之间的空格必须符合 YAML 标准。等号会破坏 YAML 对表达式的正常解释，将行的其余部分解释为 Power Fx。例如:

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

在单行公式中的任何地方都不允许使用数字符号 # 和冒号 :，即使它们是在带引号的文本字符串或标识符名称中。要使用数字符号或冒号，必须将公式表示为多行公式。数字符号在 YAML 中被解释为注释，冒号在 YAML 中被解释为新名称映射。要将注释添加到单行注释中，使用以 // 开头的 Power Fx 行注释。

不支持使用带有单引号和类似 C 的反斜杠的一般 YAML 转义；请改用多行公式。这是为了保持一致性，并辅助在 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 是具有不同模板的组件（如 Gallery）的可选说明符。并非所有组件都有模板。

如果名称包含特殊字符并用单引号引起来，则需要对冒号左侧的整个短语进行转义。可以通过以下方式之一完成此操作：

使用单引号将整个左侧引起来，这需要使用现有单引号两次：
```
'''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 允许重用相同的名称映射，最后一个以静默方式覆盖任何先前的定义。因为这会使低代码制作者感到迷惑，并且可能导致属性公式丢失，所以如果两次遇到相同的名称，将引发错误。

通过