Power Fx YAML 公式语法
备注
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
)
组件类型可以是任何画布组件或控件。 不支持基本类型,如数字。
组件模板是具有不同模板(例如库)的组件的可选说明符。 并非所有组件都有模板。
如果名称包含特殊字符并用单引号引起来,则需要对冒号左侧的整个短语进行转义。 可以通过以下方式之一完成此操作:
- 使用单引号将整个左侧引起来,这需要使用现有单引号两次:
'''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 允许重用相同的名称映射,最后一个以静默方式覆盖任何先前的定义。 因为这会使低代码制作者感到迷惑,并且可能导致属性公式丢失,所以如果两次遇到相同的名称,将引发错误。