Chia sẻ qua

Power FxNgữ pháp công thức YAML

  • Bài viết

Lưu ý

Microsoft Power Fx là tên mới của ngôn ngữ công thức cho ứng dụng canvas. Những bài viết này được thực hiện khi chúng tôi trích xuất ngôn ngữ từ các ứng dụng canvas, tích hợp ngôn ngữ đó với các sản phẩm khác của Microsoft Power Platform và hiển thị dưới dạng nguồn mở. Bắt đầu từ phần Microsoft Power Fx Tổng quan để xem thông tin giới thiệu cho ngôn ngữ này.

Microsoft Power Fx có ngữ pháp được thiết lập tốt cho các biểu thức dựa trên Excel. Tuy nhiên, khi sử dụng trong Power Apps và các máy chủ khác nơi giao diện người dùng cung cấp liên kết tên với biểu thức cho một công thức, không có cách chuẩn nào để chỉnh sửa liên kết công thức dưới dạng văn bản.

Chúng tôi đã chọn tiêu chuẩn ngành YAML như ngôn ngữ của chúng tôi cho ràng buộc này. Đã có một số lượng lớn trình chỉnh sửa, công cụ và thư viện để làm việc với YAML. Bài viết này mô tả cách chúng tôi biểu diễn các công thức trong YAML.

Tại thời điểm này, chúng tôi chỉ hỗ trợ một tập hợp con bị hạn chế của YAML. Chỉ các cấu trúc được mô tả trong bài viết này được hỗ trợ.

Không phải mọi thứ xác định ứng dụng canvas đều được trình bày ở đây; thông tin bổ sung sẽ có trong các tệp khác mà công cụ tạo ra và sử dụng.

Dấu bằng mở đầu

Đầu tiên và quan trọng nhất, tất cả các biểu thức phải bắt đầu bằng dấu bằng mở đầu =:

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

Chúng tôi sử dụng = theo cách này vì ba lý do:

  • Quy tắc này phù hợp với Excel, sử dụng = mở đầu để ràng buộc biểu thức với một ô.
  • Nó thoát khỏi cú pháp của ngôn ngữ công thức một cách hiệu quả để YAML không cố gắng phân tích cú pháp của mình. Thông thường, YAML sẽ xử lý text: 1:00 dưới dạng phút và giây, chuyển đổi thành một số. Bằng cách chèn một =, YAML sẽ không sử dụng các quy tắc nhập ngầm và các công thức sẽ không bị tổn hại. Việc sử dụng = áp dụng cho hầu hết các trường hợp, nhưng không phải tất cả và những trường hợp ngoại lệ đó được mô tả trong phần sau, Công thức một dòng.
  • Trong tương lai, chúng tôi sẽ hỗ trợ cả hai công thức (bắt đầu bằng =) và không phải công thức (không =) trong cùng một tệp, giống như Excel. Chúng tôi có thể thực hiện việc này trong các tệp YAML và không phải YAML như nhau trên các tệp nguồn Microsoft Power Platform. Bất kỳ nơi nào công thức được hỗ trợ, = đứng đầu khác với biểu thức công thức Power Apps từ một giá trị vô hướng tĩnh.

Công thức một dòng

Công thức một dòng được viết dưới dạng:

Name:SPACE=Expression

Khoảng cách giữa dấu hai chấm và dấu bằng bắt buộc phải tuân thủ YAML. Dấu bằng phá vỡ cách diễn giải biểu thức thông thường của YAML, cho phép phần còn lại của dòng được diễn giải dưới dạng Power Fx. Ví dụ: 

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

Kí hiệu số # và dấu hai chấm : không được phép ở bất kỳ đâu trong công thức một dòng, ngay cả khi chúng nằm trong chuỗi văn bản được trích dẫn hoặc tên mã định danh. Để sử dụng ký hiệu số hoặc dấu hai chấm, bạn phải biểu thị công thức dưới dạng công thức nhiều dòng. Ký hiệu số được hiểu là một chú thích trong YAML và dấu hai chấm được hiểu là một bản đồ tên mới trong YAML. Để thêm nhận xét vào nhận xét một dòng, hãy sử dụng nhận xét dòng Power Fx bắt đầu bằng //.

Sử dụng cách thoát YAML thông thường với dấu ngoặc kép đơn và dấu gạch chéo ngược giống chữ C không được hỗ trợ; thay vào đó hãy sử dụng công thức nhiều dòng. Điều này là để nhất quán và tạo điều kiện thuận lợi cho việc cắt/dán giữa thanh công thức trong Power Apps Studio và các tệp nguồn YAML.

Xem tài liệu ứng dụng canvas toán tử và định danh để biết chi tiết về các tên được phép và cấu trúc của một biểu thức.

Công thức nhiều dòng

Công thức có thể kéo dài nhiều dòng bằng cách sử dụng các chỉ báo vô hướng khối của YAML:

Name:SPACE ( | hoặc |+ hoặc |- ) =Expression-LineExpression-Line ...

Tất cả các dòng là một phần của khối phải được thụt vào ít nhất một khoảng trắng so với mức của dòng đầu tiên.

Ví dụ:

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

Ví dụ: Tất cả các dạng ký hiệu vô hướng nhiều dòng YAML đều được chấp nhận khi nhập khẩu, bao gồm >+. Tuy nhiên, để đảm bảo rằng khoảng trắng được lưu giữ đúng cách, chỉ |,|+ hoặc là |- được tạo ra.

Phiên bản thành phần

Các thành phần được thể hiện bằng cách sử dụng ký hiệu đối tượng YAML. Loại đối tượng được thiết lập bằng toán tử As như một phần của thẻ YAML bên trái. Đối với điều khiển vùng chứa, các đối tượng có thể được lồng vào nhau.

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

Tất cả các dòng là một phần của khối phải được thụt vào ít nhất một khoảng trắng so với mức của dòng đầu tiên.

Ví dụ:

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 có thể là bất kỳ thành phần hoặc điều khiển canvas nào. Các loại cơ sở, chẳng hạn như Chữ số, không được hỗ trợ.

Component-Template là một bộ chỉ định tùy chọn cho các thành phần có các mẫu khác nhau, chẳng hạn như Thư viện. Không phải tất cả các thành phần đều có mẫu.

Nếu Tên chứa các ký tự đặc biệt và được bao bọc bằng dấu ngoặc đơn, toàn bộ cụm từ ở phía bên trái của dấu hai chấm sẽ cần phải được thoát ra. Việc này có thể được thực hiện theo một trong những cách sau đây:

  • Sử dụng dấu trích dẫn đơn để bao bọc toàn bộ phía bên trái, điều này yêu cầu các dấu trích dẫn đơn hiện có được sử dụng hai lần: 
    '''A name with a space'' As Gallery':
  • Sử dụng dấu ngoặc kép để bao bọc toàn bộ phía bên trái, nhưng hãy đảm bảo rằng không có dấu ngoặc kép trong tên: 
    "'A name with a space' As Gallery":

Định nghĩa thành phần

Tương tự, các thành phần được xác định bằng cách tạo một phiên bản của một trong các kiểu cơ sở được hỗ trợ. Các loại cơ sở không thể được cài đặt trực tiếp. Trong một định nghĩa đối tượng, các thuộc tính có thể được thêm vào những gì mà kiểu cơ sở cung cấp.

Các loại cơ sở được hỗ trợ là: CanvasComponent

Định nghĩa thuộc tính đơn giản

Các thành phần sử dụng các thuộc tính để giao tiếp với ứng dụng mà chúng được lưu trữ.

Name: ( Single-Line-Expression hoặc Multi-Line-Expression )

Kiểu của công thức được ngụ ý bởi kiểu của biểu thức.

Đối với thuộc tính đầu vào, biểu thức cung cấp giá trị mặc định để được chèn vào ứng dụng khi thành phần được cài đặt sẵn. Người tạo có thể sửa đổi biểu thức này khi họ thấy phù hợp, nhưng không thể thay đổi kiểu.

Đối với các thuộc tính đầu ra, biểu thức cung cấp phép tính được thực hiện. Người tạo không thể sửa đổi biểu thức này, do biểu thức được đóng gói trong thành phần.

Tại thời điểm này, tất cả các thuộc tính chỉ là luồng dữ liệu và không thể chứa các tác dụng phụ.

Tại thời điểm này, siêu dữ liệu bổ sung về thuộc tính không được xác định ở đây mà thay vào đó được xác định trong các tệp khác của tệp .msapp, ví dụ như mô tả thuộc tính.

Ví dụ:

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

Tương thích YAML

Nhận xét YAML

Nhận xét dòng YAML được phân tách bằng ký hiệu số # không được lưu giữ ở bất kỳ đâu trong định dạng nguồn. Thay vào đó, trong một công thức, hãy phân tách các dòng nhận xét bằng ký tự // hoặc chặn nhận xét bằng /* và */. Thông tin thêm: Nhận xét

Các lỗi thường gặp

Có một số chỗ mà ngữ pháp Power Fx và YAML không tương thích hoặc có thể gây nhầm lẫn cho người dùng. Trong những trường hợp này, lỗi sẽ xảy ra.

Hãy xem ví dụ sau đây:

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

Ký hiệu số # được YAML coi như một nhận xét, ngay cả khi nó được nhúng vào thứ mà Excel coi là một chuỗi văn bản (được bao bọc bởi dấu ngoặc kép). Để tránh nhầm lẫn, trường hợp này sẽ xuất hiện một lỗi trong quá trình nhập. Có thể sử dụng biểu mẫu đa dòng YAML để thay thế.

Trong trường hợp giá trị cho record, YAML xem xét a: và b: là một ràng buộc bản đồ tên khác. YAML cho phép sử dụng lại bản đồ cùng tên, với bản đồ cuối cùng sẽ ghi đè lên bất kỳ định nghĩa nào trước đó. Bởi vì điều này có thể gây nhầm lẫn cho người tạo mã thấp và có thể dẫn đến mất công thức thuộc tính, lỗi sẽ xảy ra nếu gặp cùng một tên hai lần.