Dodawanie dokumentacji funkcji

Dodatek Power Query automatycznie wygeneruje interfejs użytkownika wywołania na podstawie argumentów funkcji. Domyślnie ten interfejs użytkownika będzie zawierać nazwę funkcji i dane wejściowe dla każdego z parametrów.

Podobnie ocena nazwy funkcji bez określania parametrów spowoduje wyświetlenie informacji o niej.

Możesz zauważyć, że wbudowane funkcje zwykle zapewniają lepsze środowisko użytkownika, opisy, etykietki narzędzi, a nawet przykładowe wartości. Ten sam mechanizm można wykorzystać, definiując określone meta wartości w typie funkcji. W tym temacie opisano meta pola, które są używane przez dodatek Power Query i jak można ich używać w rozszerzeniach.

Typy funkcji

Możesz podać dokumentację funkcji, definiując niestandardowe wartości typów . Proces wygląda następująco:

1. Zdefiniuj typ dla każdego parametru.
2. Zdefiniuj typ funkcji.
3. Dodaj różne Documentation.* pola do rekordu metadanych typów.
4. Wywołaj metodę Value.ReplaceType , aby przypisać typ funkcji udostępnionej.

Więcej informacji o typach i wartościach metadanych można znaleźć w specyfikacji języka M.

Dzięki temu podejściu można podać opisy i nazwy wyświetlane dla funkcji, a także poszczególne parametry. Możesz również podać przykładowe wartości parametrów, a także zdefiniować wstępnie ustawioną listę wartości (zamieniając domyślną kontrolkę pola tekstowego na listę rozwijaną).

Środowisko Dodatku Power Query pobiera dokumentację z wartości meta na typ funkcji przy użyciu kombinacji wywołań funkcji Value.Type, Type.FunctionParameters i Value.Metadata.

Dokumentacja funkcji

W poniższej tabeli wymieniono pola Dokumentacja, które można ustawić w metadanych funkcji. Wszystkie pola są opcjonalne.

Pole	Typ	Szczegóły
Documentation.Examples	lista	Lista obiektów rekordów z przykładowym użyciem funkcji. Wyświetlane tylko jako część informacji o funkcji. Każdy rekord powinien zawierać następujące opcjonalne pola tekstowe: Description, Codei Result.
Documentation.LongDescription	text	Pełny opis funkcji wyświetlanej w informacjach o funkcji.
Documentation.Name	text	Tekst wyświetlany w górnej części okna dialogowego wywołania funkcji.

Dokumentacja parametrów

W poniższej tabeli wymieniono pola Dokumentacja, które można ustawić w metadanych parametrów funkcji. Wszystkie pola są opcjonalne.

Pole	Typ	Szczegóły
Documentation.AllowedValues	lista	Lista prawidłowych wartości dla tego parametru. Podanie tego pola spowoduje zmianę danych wejściowych z pola tekstowego na listę rozwijaną. Należy pamiętać, że nie uniemożliwia to użytkownikowi ręcznego edytowania zapytania w celu podania wartości alternatywnych.
Documentation.FieldCaption	text	Przyjazna nazwa wyświetlana do użycia dla parametru .
Documentation.FieldDescription	text	Opis wyświetlany obok nazwy wyświetlanej.
Documentation.SampleValues	lista	Lista przykładowych wartości do wyświetlenia (jako wyblakłego tekstu) w polu tekstowym.
Formatting.IsMultiLine	boolean	Umożliwia utworzenie danych wejściowych wielowierszowych, na przykład do wklejania w zapytaniach natywnych.
Formatting.IsCode	boolean	Formatuje pole wejściowe dla kodu, często z danymi wejściowymi wielowierszowymi. Używa czcionki przypominającej kod, a nie standardowej czcionki.

Przykład podstawowy

Poniższy fragment kodu (i wynikowe okna dialogowe) pochodzi z przykładu HelloWorldWithDocs .

[DataSource.Kind="HelloWorldWithDocs", Publish="HelloWorldWithDocs.Publish"]
shared HelloWorldWithDocs.Contents = Value.ReplaceType(HelloWorldImpl, HelloWorldType);

HelloWorldType = type function (
    message as (type text meta [
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

HelloWorldImpl = (message as text, optional count as number) as table =>
    let
        _count = if (count <> null) then count else 5,
        listOfMessages = List.Repeat({message}, _count),
        table = Table.FromList(listOfMessages, Splitter.SplitByNothing())
    in
        table;

Ten kod powoduje wyświetlenie następujących okien dialogowych w usłudze Power BI.

Wywołanie funkcji

Informacje o funkcji

Przykład wielowierszowy

[DataSource.Kind="HelloWorld", Publish="HelloWorld.Publish"]
shared HelloWorld.Contents =
    let
        HelloWorldType = type function (
            message1 as (type text meta [
                Documentation.FieldCaption = "Message 1",
                Documentation.FieldDescription = "Text to display for message 1",
                Documentation.SampleValues = {"Hello world"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = true
            ]),
            message2 as (type text meta [
                Documentation.FieldCaption = "Message 2",
                Documentation.FieldDescription = "Text to display for message 2",
                Documentation.SampleValues = {"Hola mundo"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = false
            ])) as text,
        HelloWorldFunction = (message1 as text, message2 as text) as text => message1 & message2
    in
        Value.ReplaceType(HelloWorldFunction, HelloWorldType);

Ten kod (ze skojarzonymi informacjami o publikowaniu itd.) powoduje wyświetlenie następującego okna dialogowego w usłudze Power BI. Nowe wiersze będą reprezentowane w tekście przy użyciu znaku "#(lf)" lub "kanału informacyjnego wiersza".