Bagikan melalui

Power FxTata bahasa rumus YAML

  • Artikel

Catatan

Microsoft Power Fx adalah nama baru untuk bahasa rumus untuk aplikasi kanvas. Artikel-artikel ini sedang berlangsung saat kami mengekstrak bahasa dari aplikasi kanvas, mengintegrasikannya dengan produk Microsoft Power Platform lain, dan membuatnya tersedia sebagai sumber terbuka. Mulai dengan Gambaran Umum Microsoft Power Fx untuk pengenalan bahasa.

Microsoft Power Fx memiliki tata bahasa yang mapan untuk ekspresi berdasarkan Excel. Namun, bila digunakan dalam Power Apps dan host lain di mana UI menyediakan ikatan nama terhadap ekspresi untuk rumus, tidak ada cara standar untuk mengedit ikatan rumus sebagai teks.

Kami telah memilih YAML standar industri sebagai bahasa kami untuk ikatan ini. Sudah ada sejumlah besar editor, alat bantu, dan pustaka untuk bekerja dengan YAML. Artikel ini menjelaskan cara kami menunjukkan rumus dalam YAML.

Pada saat ini, kami hanya mendukung subset YAML yang dibatasi. Hanya konstruk yang dijelaskan dalam artikel ini yang didukung.

Tidak semua yang mendefinisikan aplikasi kanvas ditunjukkan di sini; informasi tambahan mengalir melalui file lain yang dihasilkan dan digunakan oleh alat.

Tanda sama dengan di depan

Pertama dan terpenting, semua ekspresi harus dimulai dengan tanda sama dengan = yang terkenal:

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

Kami menggunakan = dengan cara ini karena tiga alasan:

  • Hal ini sesuai dengan Excel, yang menggunakan = di depan untuk mengikat ekspresi ke sel.
  • Ia secara efektif melepaskan diri dari sintaks bahasa rumus sehingga YAML tidak mencoba mengurainya. Biasanya, YAML akan memperlakukan text: 1:00 sebagai menit dan detik, mengkonversinya ke angka. Dengan memasukkan =, YAML tidak akan menggunakan aturan mengetik implisitnya dan rumus tidak akan terganggu. Menggunakan = mencakup sebagian besar kasus, namun tidak semua, dan pengecualian tersebut dijelaskan pada bagian berikut, Rumus satu baris.
  • Di masa mendatang, kami akan mendukung kedua rumus (diawali dengan =) dan non-rumus (tidak ada =) di file yang sama, sama seperti Excel, kita juga dapat melakukannya di file YAML dan non-YAML di seluruh file sumber Microsoft Power Platform. Di mana pun rumusnya didukung, = depan membedakan ekspresi rumus Power Apps dari nilai skalar statis.

Rumus Satu Baris

Rumus satu baris ditulis dalam formulir:

Name:SPACE=Expression

Spasi antara titik dua dan tanda sama dengan diperlukan agar sesuai dengan YAML. Tanda sama dengan mengganggu interpretasi normal YAML terhadap ekspresi tersebut, sehingga sisa barisnya diinterpretasikan sebagai Power Fx. Contoh: 

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

tanda nomor # dan titik dua : tidak dibolehkan di mana pun dalam rumus baris tunggal, meskipun berada dalam string teks atau nama pengidentifikasi yang berkutip. Untuk menggunakan tanda nomor atau titik dua, Anda harus mengekspresikan rumus sebagai rumus multibaris. Tanda nomor ditafsirkan sebagai komentar dalam YAML, dan titik dua diartikan sebagai peta nama baru di YAML. Untuk menambahkan komentar ke komentar satu baris, gunakan komentar baris Power Fx yang dimulai dengan //.

Menggunakan YAML biasa yang keluar dengan tanda kutip tunggal dan garis miring terbalik seperti C tidak didukung; gunakan rumus multibaris. Hal ini untuk konsistensi dan memudahkan potong/rekat antara bilah rumus dalam Power Apps Studio dan file sumber YAML.

Untuk detail tentang nama yang diizinkan dan struktur ekspresi, lihat dokumentasi operator dan pengidentifikasi aplikasi kanvas.

Rumus multi-baris

Rumus dapat menjangkau beberapa baris menggunakan indikator skalar blok YAML:

Name:SPACE ( | or |+ or |- ) =Expression-LineExpression-Line ...

Semua baris yang merupakan bagian dari blok harus terindentasi sekurangnya satu spasi dari tingkat baris pertama.

Contoh: 

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

Semua bentuk notasi skalar multi-baris YAML diterima saat impor, termasuk >+, misalnya. Namun, untuk memastikan bahwa spasi kosong disimpan dengan benar, hanya |, |+, atau |- yang dihasilkan.

Instans komponen

Komponen di-instans menggunakan notasi objek YAML. Jenis objek ditetapkan dengan operator As sebagai bagian dari tag YAML sisi kiri. Untuk kontrol wadah, objek dapat dikurung.

NameAsComponent-Type [ .Component-Template ] : ( Single-Line-Formula or Multi-Line-Formula or Object-instance ) ...

Semua baris yang merupakan bagian dari blok harus terindentasi sekurangnya satu spasi dari tingkat baris pertama.

Contoh: 

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 dapat berupa kontrol atau komponen kanvas apa pun. Jenis dasar, seperti Angka, tidak didukung.

Component-Template merupakan penentu opsional untuk komponen yang memiliki templat berbeda, seperti Galeri. Tidak semua komponen memiliki template.

Jika Nama berisi karakter khusus dan dibungkus dengan satu tanda kutip, seluruh frasa di sisi kiri titik dua harus di-escape. Ini dapat dilakukan dalam salah satu dari cara berikut:

  • Gunakan tanda petik satu untuk membungkus sisi kiri seluruhnya, yang artinya tanda petik satu yang ada harus dicantumkan dua kali: 
    '''A name with a space'' As Gallery':
  • Gunakan tanda petik dua untuk membungkus sisi kiri seluruhnya, tetapi pastikan bahwa tidak ada tanda petik dua di nama: 
    "'A name with a space' As Gallery":

Definisi Komponen

Dengan cara yang sama, komponen didefinisikan dengan membuat instans dari salah satu tipe dasar yang didukung. Jenis dasar tidak dapat di-instans secara langsung. Dalam definisi objek, properti dapat ditambahkan ke yang disediakan tipe dasar.

Tipe dasar yang didukung adalah: CanvasComponent

Definisi properti sederhana

Komponen menggunakan properti untuk berkomunikasi dengan aplikasi tempatnya di-host.

Name: ( Single-Line-Expression or Multi-Line-Expression )

Tipe rumus tersirat berdasarkan tipe ekspresi.

Untuk properti input, ekspresi memberikan default untuk dimasukkan ke dalam aplikasi saat komponen dibuat instansnya. Pembuat dapat memodifikasi ekspresi ini sesuai kebutuhan, namun tidak dapat mengubah jenisnya.

Untuk properti output, ekspresi memberikan penghitungan yang akan dilakukan. Pembuat tidak dapat memodifikasi ekspresi ini, ia dikemas dalam komponen.

Pada saat ini, semua properti hanya merupakan aliran data dan tidak dapat berisi efek samping.

Pada saat ini, metadata tambahan tentang properti tidak didefinisikan di sini, namun didefinisikan di file lain dari file .msapp, misalnya deskripsi properti.

Contoh: 

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

Kompatibilitas YAML

Komentar YAML

Komentar baris YAML yang dibatasi oleh tanda nomor # tidak disimpan dalam format sumber. Sebagai gantinya, dalam rumus, batasi komentar baris dengan karakter // atau blokir komentar dengan /* dan */. Informasi Selengkapnya: Komentar

Kesalahan untuk jebakan umum

Ada beberapa tempat di mana tata bahasa YAML dan Power Fx tidak kompatibel atau mungkin membingungkan bagi pengguna. Dalam kasus ini, terjadi kesalahan.

Misalnya, dalam contoh berikut:

Text: ="Hello #PowerApps"
Record: ={ a: 1, b: 2 }

Tanda nomor # dianggap sebagai komentar oleh YAML, meskipun disematkan dalam apa yang dianggap Excel sebagai string teks (dikurung dengan tanda kutip ganda). Untuk menghindari kebingungan, kasus ini akan menimbulkan kesalahan selama impor. Formulir multiline YAML dapat digunakan.

Dalam kasus nilai untuk record, YAML menganggap a: dan b: sebagai ikatan peta nama lain. YAML memungkinkan peta nama yang sama digunakan kembali, dengan yang terakhir secara hening mengganti definisi sebelumnya. Karena hal ini dapat membingungkan untuk pembuat kode rendah dan dapat mengakibatkan hilangnya rumus properti, kesalahan akan dihasilkan jika nama yang sama terjadi dua kali.