Přidání dokumentace k funkcím

Power Query automaticky vygeneruje uživatelské rozhraní vyvolání za vás na základě argumentů vaší funkce. Ve výchozím nastavení bude toto uživatelské rozhraní obsahovat název vaší funkce a vstup pro každý z vašich parametrů.

Podobně vyhodnocení názvu funkce bez zadání parametrů zobrazí informace o této funkci.

Můžete si všimnout, že integrované funkce obvykle poskytují lepší uživatelské prostředí s popisy, popisy a dokonce i ukázkovými hodnotami. Stejný mechanismus můžete využít definováním konkrétních meta hodnot pro váš typ funkce. Toto téma popisuje metadata, která power Query používá, a způsob jejich použití ve vašich rozšířeních.

Typy funkcí

Dokumentaci pro funkci můžete poskytnout definováním hodnot vlastních typů . Proces vypadá takto:

1. Definujte typ pro každý parametr.
2. Definujte typ funkce.
3. Do záznamu metadat typů přidejte různá Documentation.* pole.
4. Volání Value.ReplaceType pro přiřazení typu ke sdílené funkci.

Další informace o typech a hodnotách metadat najdete ve specifikaci jazyka M.

Pomocí tohoto přístupu můžete zadat popisy a zobrazované názvy funkce a také jednotlivé parametry. Můžete také zadat ukázkové hodnoty parametrů a také definovat přednastavený seznam hodnot (otáčení výchozího ovládacího prvku textového pole do rozevíracího seznamu).

Prostředí Power Query načte dokumentaci z meta hodnot typu funkce pomocí kombinace volání Value.Type, Type.FunctionParameters a Value.Metadata.

Dokumentace k funkcím

Následující tabulka uvádí pole Dokumentace, která lze nastavit v metadatech vaší funkce. Všechna pole jsou volitelná.

Pole	Typ	Detaily
Documentation.Examples	list	Seznam objektů záznamů s příkladem použití funkce Zobrazí se jenom jako součást informací o funkci. Každý záznam by měl obsahovat následující volitelná textová pole: Description, Codea Result.
Documentation.LongDescription	text	Úplný popis toho, co funkce dělá, zobrazených v informacích o funkci.
Documentation.Name	text	Text, který se má zobrazit v horní části dialogového okna vyvolání funkce

Dokumentace k parametrům

Následující tabulka uvádí pole Dokumentace, která lze nastavit v metadatech pro parametry funkce. Všechna pole jsou volitelná.

Pole	Typ	Detaily
Documentation.AllowedValues	list	Seznam platných hodnot pro tento parametr Pokud toto pole zadáte, změní se vstup z textového pole na rozevírací seznam. Poznámka: Nezabráníte tomu, aby uživatel ručně upravil dotaz tak, aby zadává alternativní hodnoty.
Documentation.FieldCaption	text	Popisný zobrazovaný název, který se má použít pro parametr.
Documentation.FieldDescription	text	Popis, který se má zobrazit vedle zobrazovaného názvu
Documentation.SampleValues	list	Seznam ukázkových hodnot, které se mají zobrazit (jako zesvětlený text) uvnitř textového pole
Formatting.IsMultiLine	boolean	Umožňuje vytvořit víceřádkový vstup, například pro vkládání v nativních dotazech.
Formatting.IsCode	boolean	Formátuje vstupní pole pro kód, běžně se vstupy s více řádky. Používá místo standardního písma písmo podobné kódu.

Základní příklad

Následující fragment kódu (a výsledné dialogy) jsou z ukázky 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;

Výsledkem tohoto kódu jsou následující dialogy v Power BI.

Vyvolání funkce

Informace o funkci

Příklad s více řádky

[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);

Výsledkem tohoto kódu (s přidruženými informacemi o publikování atd.) je následující dialog v Power BI. Nové řádky budou reprezentovány v textu s textem #(lf) nebo "spojnicovým kanálem".