Power FxYAML 公式文法

發行項
10/16/2024

注意

Microsoft Power Fx 是畫布應用程式語言的新名稱。當我們從畫布應用程式中擷取語言，將其與其他 Microsoft Power Platform 產品整合並打造開放原始碼時，這些文章仍會持續進行。從 Microsoft Power Fx 概覽開始以取得對該語言的介紹。

Microsoft Power Fx 擁有針對基於 Excel 型運算式的完善語法。但是，在 UI 為公式提供名稱到運算式繫結的 Power Apps 和其他主機中使用時，沒有標準方法可以將公式繫結編輯為文字。

我們選擇了產業標準 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 }

即使數字符號 # 嵌入在 Excel 認為是文字字串 (用雙引號括起來的字符) 中，也會被 YAML 視為留言。若要避免混淆，這種情況將在匯入期間引發錯誤。可以使用 YAML 多行形式。

對於 record 值，YAML 認為 a: 和 b: 是另一個名稱對應繫節。 YAML 允許重新使用相同的名稱對應，最後一個會沉默地覆蓋任何先前的定義。因為這會使低階代碼製作者感到困惑，並且可能導致屬性公式的丟失，所以如果兩次遇到相同的名稱則會引發錯誤。

共用方式為