Power FxYAML 式の文法

  • [アーティクル]

Note

Microsoft Power Fx は、キャンバス アプリ用の数式言語の新しい名前です。 これらの記事は、キャンバス アプリから言語を抽出し、その他の Microsoft Power Platform 製品と統合して、オープン ソースとして利用できるようにするために進行中の作業です。 言語の紹介のために Microsoft Power Fx の概要 から開始します。

Microsoft Power Fx には Excel に基づく式の文法が確立されています。 ただし、Power Apps や UI が数式の名前から式へのバインディングを提供するその他のホストで使われる場合、数式のバインディングをテキストとして編集する標準的な方法はありません。

このバインディングの言語として、Microsoft は業界標準である YAML を選択しました。 YAML を操作するためのエディター、ツール、ライブラリーはすでに多数あります。 この記事では、YAML で数式を表現する方法について説明します。

現時点では、YAML の限定されたサブセットのみをサポートしています。 サポートされているのは、この記事で説明されている構成のみです。

キャンバス アプリを定義するすべてがここに表示されているわけではなく、追加情報は、ツールが生成および処理する他のファイルを介して流れます。

先頭の等号

何よりもまず、すべての式は先頭の等号 = で始まる必要があります。

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

= をこのように使用する理由は 3 つあります。

  • それは式をセルにバインドするための Excel の行頭 = の使用法と一致しています。
  • YAML が解析を試みないように、数式言語の構文を効果的にエスケープします。 通常、YAML は text: 1:00 を分と秒とし、それを数値に変換します。 = を挿入することによって、YAML は暗黙の入力規則を使用せず、数式に悪影響を与えません。 = の使用はすべてではありませんがほとんどの場合をカバーしており、例外については、次のセクション 1 行の数式 で説明します。
  • 将来的には、Excel と同じように、同じファイル内で数式 (= で始まるもの) と 数式以外 (= で始まらないもの) をサポートする予定であり、これは Microsoft Power Platform ソース ファイル全体において YAML ファイルおよび 非 YAML ファイルで同様に行うことができます。 数式がサポートされている場所ならどこでも、行頭の = により、Power Apps 数式と静的スカラー値を区別できます。

1 行の数式

1 行の数式は、次の形式で記述されます。

名前:SPACE=式

コロンと等号の間のスペースは、YAML に準拠している必要があります。 等号は、YAML による式の通常の解釈を中断し、行の残りの部分を Power Fx として解釈できるようにします。 例:

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

番号記号 # とコロン : は、引用符で囲まれたテキスト文字列または識別子名であっても、1 行の数式では一切使用できません。 番号記号またはコロンを使用するには、数式を複数行の数式として表現する必要があります。 番号記号は YAML ではコメントとして解釈され、YAML ではコロンが新しい名前マップとして解釈されます。 単一行コメントにコメントを追加するには、// で始まる Power Fx の行コメントを使用します。

単一引用符や C 言語のバックスラッシュを使用した標準の YAML エスケープの使用はサポートされていないので、代わりに複数行の数式を使用してください。 これは一貫性を保つためであり、Power Apps Studio および YAML ソース ファイルの数式バーの間の切り取り/貼り付けを容易にするためです。

許可される名前と式の構造の詳細については、キャンバス アプリの演算子と識別子ドキュメントを参照してください。

複数行の数式

数式は、YAML のブロック スカラー インジケーターを使用して複数行にまたがることができます。

名前:SPACE ( | または |+ または |- ) =Expression-LineExpression-Line ...

ブロックの一部であるすべての行は、最初の行のレベルから少なくともスペース 1 つ分インデントする必要があります。

例: 

Text1: |
    ="Hello, World"
Text2: |
    ="Hello" &
    "," &
    "World"

たとえば >+ のようなすべての形式の YAML 複数行スカラー表記をインポート時に受け入れます。 ただし、空白が適切に保持されるように、|、|+、または |- のみが生成されます。

コンポーネント インスタンス

コンポーネントは、YAML オブジェクト表記を使用してインスタンス化されます。 オブジェクトのタイプは、As 演算子を左側の YAML タグの一部として確立されます。 コンテナ コントロールの場合、オブジェクトをネストできます。

名前AsComponent-Type [ .Component-Template ] : ( Single-Line-Formula または Multi-Line-Formula または Object-instance ) ...

ブロックの一部であるすべての行は、最初の行のレベルから少なくともスペース 1 つ分インデントする必要があります。

例: 

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":

コンポーネント定義

同様に、コンポーネントは、サポートされている基本タイプの 1 つのインスタンスを作成することによって定義されます。 基本タイプを直接インスタンス化することはできません。 オブジェクト定義内で、基本タイプが提供するものにプロパティを追加できます。

サポートされているデータのタイプは: CanvasComponent

簡単なプロパティ定義

コンポーネントは、プロパティを使用して、それらがホストされているアプリと通信します。

名前: ( Single-Line-Expression または Multi-Line-Expression )

式のタイプは、式のタイプによって示されます。

入力プロパティの場合、式はコンポーネントがインスタンス化されたときにアプリに挿入される既定値を提供します。 作成者はこの式を必要に応じて変更できますが、タイプを変更することはできません。

出力プロパティの場合、式は実行される計算を提供します。 コンポーネントにカプセル化されているので、作成者はこの式を変更できません。

現時点では、すべてのプロパティはデータ フローのみであり、副作用を含めることはできません。

現時点では、プロパティに関する追加のメタデータはここでは定義されていませんが、代わりに、たとえばプロパティの説明などが .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 を使用すると、同じ名前マップを再利用でき、最後のマップは、以前の定義をサイレントに上書きします。 これはロー コード メーカーにとって混乱を招き、プロパティの式が失われる可能性があるため、同じ名前が 2 回検出されると、エラーがスローされます。