Udostępnij za pośrednictwem

Power FxGramatyka formuły YAML

Uwaga

Microsoft Power Fx to nowa nazwa języka formuł dla aplikacji kanw. Te artykuły są pracą w toku, gdyż stale wyodrębniamy język z aplikacji kanw, integrujemy go z innymi produktami Microsoft Power Platform i udostępniamy jako rozwiązanie open source. Zacznij od przeglądu Microsoft Power Fx, aby znaleźć wprowadzenie do języka.

Microsoft Power Fx używa dobrze znanej gramatyki wyrażeń z Excel. Jednak gdy są używane w Power Apps i innych hostach, gdzie interfejs użytkownika zawiera powiązanie nazwy z wyrażeniem dla formuły, nie istnieje standardowy sposób edytowania formuły wiążącej jako tekst.

Wybraliśmy znany w branży standard YAML jako język tego powiązania. Jest już wiele edytorów, narzędzi i bibliotek do pracy z zestawem YAML. W tym artykule opisano, w jaki sposób reprezentujemy formuły w technologii YAML.

W tym momencie obsługujemy tylko ograniczony podzbiór zestawu YAML. Obsługiwane są tylko konstruktory opisane w tym artykule.

Nie wszystko, co definiuje aplikację kanw, jest tutaj reprezentowane; więc dodatkowe informacje spływają za pośrednictwem innych plików, które narzędzie generuje i zużywa.

Wiodący znak równości

Wszystkie wyrażenia muszą rozpoczynać się od znaku równości =:

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

Korzystamy z = z trzech powodów:

  • Jest to zachowanie spójne z programem Excel, który używa wiodącej = do wiązania wyrażenia z komórką.
  • W praktyce oznacza to, że składnia języka umożliwia YAML zignorowanie formuły i brak jej analizy. Zwykle YAML traktuje text: 1:00 jako minuty i sekundy, konwertując to na liczbę. Dzięki wstawianiu = YAML nie będzie używać niejawnych reguł zapisu i formuła pozostanie niezmieniona. Używanie = rozwiązuje większość problemów (ale nie wszystkie). Wyjątki opisano w następnej sekcji pt. formuły jednowierszowe.
  • W przyszłości będziemy obsługiwać zarówno formuły (zaczynające się od =) jak i ciągi inne niż formuły zaczynające się od = w tym samym pliku, tak jak w przypadku programu Excel. Możemy to zrobić zarówno w plikach YAML, jak i w plikach źródłowych innych niż YAML w Microsoft Power Platform. Tam, gdzie obsługiwana jest formuła, otwierający znak = odróżnia wyrażenie formuły Power Apps od statycznej wartości skalarnej.

Formuły jednowierszowe

Formuły jednowierszowe są zapisane w formularzu:

Wyrażenie nazwy:SPACE=

Spacja między dwukropkiem a znakiem równości jest wymagana, aby być zgodna ze standardem YAML. Znak równości zakłóci normalną interpretację wyrażenia przez YAML, co umożliwia interpretowanie pozostałej części wiersza jako Power Fx. Na przykład: 

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

Znak kratki (#) i dwukropek (:) nie są dozwolone w żadnym miejscu w formułach jednowierszowych, nawet jeśli są w cudzysłowie lub występują jako nazwa identyfikatora. Aby użyć kratki lub dwukropka, należy wyrazić formułę jako formułę wielowierszową. Znak kratki jest interpretowany jako komentarz w YAML, a dwukropek jest interpretowany jako nowe mapowanie nazwy. Aby dodać komentarz do komentarza jednowierszowego, użyj komentarza wiersza Power Fx zaczynającego się od //.

Używanie normalnej ucieczki YAML z pojedynczym cudzysłowem i ukośnikami nie jest obsługiwane. Skorzystaj z formuły wielowierszowej. Ma to zapewnić spójność i ułatwić wycinanie/wklejanie między paskami formuł w Power Apps Studio i plikach źródłowych YAML.

Szczegółowe informacje na temat dozwolonych nazw i struktury wyrażenia można znaleźć w dokumentacji aplikacji kanw dotyczącej operatorów i identyfikatorów.

Formuły wielowierszowe

Formuły mogą obejmować wiele wierszy przy użyciu blokowych wskaźników skalarnych YAML.

Nazwa:SPACE ( | lub |+|- ) =Wiersz-wyrażeniaWiersz-wyrażenia ...

Wszystkie wiersze, które są częścią bloków, muszą być wcinane na co najmniej jedno miejsce na poziomie pierwszego wiersza.

Na przykład: 

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

Wszystkie notacje skalarne YAML są akceptowane podczas importu, w tym na przykład >+. Aby jednak upewnić się, że spacja została poprawnie zachowana, tworzone są tylko |, |+ i |-.

Wystąpienie składnika

Składniki są wystąpieniem przy użyciu notacji obiektu YAML. Typ obiektu jest ustalany przez operator As jako część znacznika YAML po lewej. W przypadku formantów kontenerów obiekty mogą być zagnieżdżone.

Nazwa Typ-komponentuAs[ Szablon-komponentu .] ( : Formuła-jednowierszowa lub formuła-wielowierszowa lub instancja obiektu ) ...

Wszystkie wiersze, które są częścią bloków, muszą być wcinane na co najmniej jedno miejsce na poziomie pierwszego wiersza.

Na przykład: 

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 może być dowolnym składnikiem kanwy lub kontrolką. Typy podstawowe, takie jak Liczba, nie są obsługiwane.

Component-Template jest opcjonalnym specyfikatorem dla składników, które mają różne szablony, takie jak Galeria. Nie wszystkie składniki mają szablony.

Jeśli nazwa zawiera znaki specjalne i zostanie otoczona pojedynczymi cudzysłowami, trzeba będzie przechować całą frazę po lewej stronie dwukropka. Można to osiągnąć w dowolny z wymienionych sposobów:

  • Do owinięcia całej lewej strony wykorzystać pojedyncze cudzysłowy. Wymaga to, aby istniejące cudzysłowy pojedyncze używane były dwa razy: 
    '''A name with a space'' As Gallery':
  • Do owinięcia całej lewej strony należy użyć cudzysłowów podwójnych, ale należy się upewnić, że w nazwie nie ma cudzysłowów: 
    "'A name with a space' As Gallery":

Definicja składnika

Składniki są definiowane przez utworzenie wystąpienia jednego z obsługiwanych typów podstawowych. Nie można tworzyć wystąpienia typów podstawowych bezpośrednio. W definicji obiektu można dodać właściwości do zawartości typu podstawowego.

Obsługiwane typy podstawowe to: CanvasComponent

Definicja właściwości prostej

Składniki używają właściwości do komunikowania się z aplikacją, w której są hostowane.

Nazwa: ( wyrażenie jednowierszowe lub wyrażenie wielowierszowe)

Typ formuły zostanie poszukany przez typ wyrażenia.

W przypadku właściwości wejściowych to wyrażenie umożliwia domyślne wstawiane do aplikacji podczas wystąpienia składnika. Producent może zmodyfikować to wyrażenie zgodnie z ustawieniami, ale nie może zmienić typu.

W przypadku właściwości wyjściowych wyrażenie zawiera obliczenia, które należy wykonać. Producent nie może zmodyfikować tego wyrażenia, ale jest ono schowane w składniku.

Obecnie wszystkie właściwości są tylko właściwościami przepływu danych i nie mogą zawierać efektów ubocznych.

W tym momencie dodatkowe metadane dotyczące właściwości nie są tutaj opisane, ale są zdefiniowane w innych plikach pliku .msapp, na przykład w opisie właściwości.

Na przykład: 

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

Zgodność z YAML

Komentarze YAML

Komentarze wiersza YAML rozdzielane znakiem kratki # nie są zachowywane w formacie źródłowym. Zamiast tego w formule ogranicz komentarze w wierszu za pomocą znaków // lub zablokuj dodawanie komentarzy przy użyciu /* oraz */. Więcej informacji: Komentarze

Często występujące błędy

Istnieje kilka miejsc, w których gramatyki Power Fx i YAML są niekompatybilne lub mogą być mylące. W tych przypadkach jest wyświetlany błąd.

Na przykład w poniższym przykładzie:

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

Znak kratki # jest traktowany jak komentarz przez YAML, mimo że jest osadzony w czymś, co program Excel uzna za ciąg tekstowy (otoczone przez cudzysłów podwójny). Aby uniknąć nieporozumień, ta sytuacja zgłosi błąd podczas importowania. Należy zamiast tego użyć formularza wielowierszowego YAML.

W przypadku wartości dla record, YAML uznaje a: oraz b: za inne powiązanie mapowania nazw. YAML pozwala wielokrotnie używać tego samego mapowania nazw, a ostatnie zastępuje wszystkie poprzednie definicje. Ponieważ może to być mylące dla twórcy o niskich umiejętnościach koderskich i może spowodować utratę formuły właściwości, zgłaszany jest błąd, jeśli dwukrotnie pojawia się ta sama nazwa.