Pridanie dokumentácie k funkcii

Power Query automaticky vygeneruje vyvolanie používateľského rozhrania na základe argumentov pre vašu funkciu. Toto používateľské rozhranie bude predvolene obsahovať názov funkcie a vstup pre každý z vašich parametrov.

Podobne sa pri vyhodnocovaní názvu funkcie bez zadávania parametrov zobrazia informácie o nej.

Možno si všimnete, že vstavané funkcie zvyčajne poskytujú lepšie používateľské prostredie s popismi, popismi a dokonca vzorovými hodnotami. Rovnaký mechanizmus môžete využiť definovaním špecifických metaúdajov vo vašom type funkcie. Táto téma popisuje meta polia, ktoré Power Query používa, a ako ich môžete využiť vo svojich rozšíreniach.

Typy funkcií

Definovaním hodnôt vlastných typov môžete zadať dokumentáciu k funkcii. Proces vyzerá takto:

1. Definujte typ pre každý parameter.
2. Definujte typ funkcie.
3. Pridajte rôzne Documentation.* polia do záznamu metaúdajov typov.
4. Volajte funkciu Value.ReplaceType , čím typ pripíšete k zdieľanej funkcii.

Ďalšie informácie o typoch a hodnotách metaúdajov nájdete v špecifikácii jazyka M.

Pomocou tohto prístupu môžete zadať popisy a zobrazované názvy funkcie, ako aj jednotlivé parametre. Môžete tiež zadať vzorové hodnoty pre parametre a definovať prednastavený zoznam hodnôt (transformácia predvoleného ovládacieho prvku textového poľa na rozbaľovací zoznam).

Prostredie Power Query načíta dokumentáciu z meta hodnôt typu funkcie pomocou kombinácie volaní na Value.Type, Type.FunctionParameters a Value.Metadata.

Dokumentácia k funkcii

Nasledujúca tabuľka obsahuje zoznam polí Dokumentácia, ktoré možno nastaviť v metaúdajoch pre vašu funkciu. Všetky polia sú voliteľné.

Pole	Typ	Podrobnosti
Dokumentácia.Príklady	Zoznam	Zoznam objektov záznamu s ukážkovým použitím funkcie. Zobrazujú sa iba ako súčasť informácií o funkcii. Každý záznam by mal obsahovať nasledujúce voliteľné textové polia: Description, Codea Result.
Documentation.LongDescription	text	Úplný popis toho, čo funkcia robí, sa zobrazí v informáciách o funkcii.
Documentation.Name	text	Text, ktorý sa zobrazí v hornej časti dialógového okna vyvolania funkcie.

Dokumentácia k parametru

Nasledujúca tabuľka obsahuje zoznam polí Dokumentácia, ktoré možno nastaviť v metaúdajoch parametrov funkcie. Všetky polia sú voliteľné.

Pole	Typ	Podrobnosti
Documentation.AllowedValues	Zoznam	Zoznam platných hodnôt pre tento parameter. Za predpokladu, že toto pole zmení vstup z textového poľa na rozbaľovací zoznam. Všimnite si, že to nebráni používateľovi manuálne upravovať dotaz a dodávať alternatívne hodnoty.
Documentation.FieldCaption	text	Popisný zobrazovaný názov, ktorý sa použije pre parameter.
Documentation.FieldDescription	text	Popis, ktorý sa zobrazí vedľa zobrazovaného názvu.
Documentation.SampleValues	Zoznam	Zoznam vzorových hodnôt, ktoré sa majú zobraziť (ako vyblednutý text) vo vnútri textového poľa.
Formatting.IsMultiLine	boolovská hodnota	Umožňuje vytvoriť viacriadkový vstup, napríklad na prilepenie v natívnych dotazoch.
Formatting.IsCode	boolovská hodnota	Formátuje vstupné pole pre kód, bežne s viacriadkovými vstupmi. Namiesto štandardného písma používa písmo podobné kódu.

Základný príklad

Nasledujúci zlomok kódu (a výsledné dialógové okná) sú z ukážky 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ýsledkom tohto kódu sú nasledujúce dialógové okná v službe Power BI.

Vyvolanie funkcie

Informácie o funkcii

Viacriadkový príklad

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

Tento kód (s priradenými informáciami o publikovaní atď.) bude obsahovať nasledujúci dialóg v službe Power BI. Nové riadky budú znázornené v texte s znakom #(lf)" alebo "posun riadka".