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