Függvénydokumentáció hozzáadása

A Power Query automatikusan létrehoz egy meghívási felhasználói felületet a függvény argumentumai alapján. Alapértelmezés szerint ez a felhasználói felület tartalmazza a függvény nevét és az egyes paraméterek bemenetét.

Hasonlóképpen, a függvény nevének kiértékelése paraméterek megadása nélkül is megjeleníti az ezzel kapcsolatos információkat.

Észreveheti, hogy a beépített függvények általában jobb felhasználói élményt nyújtanak leírásokkal, elemleírásokkal és akár mintaértékekkel. Ezt a mechanizmust kihasználhatja, ha meghatározott metaértékeket határoz meg a függvénytípuson. Ez a témakör a Power Query által használt metamezőket és azok bővítményekben való használatát ismerteti.

Függvénytípusok

A függvény dokumentációját egyéni típusértékek megadásával is megadhatja. A folyamat a következőképpen néz ki:

1. Adjon meg egy típust az egyes paraméterekhez.
2. Adjon meg egy típust a függvényhez.
3. Adjon hozzá különböző Documentation.* mezőket a típusok metaadat-rekordjához.
4. A Value.ReplaceType hívásával írja le a típust a megosztott függvényhez.

A típusokról és a metaadatértékekről az M nyelvi specifikációban talál további információt.

Ezzel a módszerrel leírásokat és megjelenítendő neveket adhat meg a függvényhez, valamint az egyes paramétereket. A paraméterekhez mintaértékeket is megadhat, valamint előre beállított értéklistát is meghatározhat (az alapértelmezett szövegdoboz-vezérlőt legördülő listává alakíthatja).

A Power Query-felület a függvény típusának metaértékeiből kéri le a dokumentációt a Value.Type, Type.FunctionParameters és Value.Metadata hívások kombinációjával.

Függvénydokumentáció

Az alábbi táblázat a függvény metaadataiban beállítható dokumentációs mezőket sorolja fel. A mezők egyike sem kötelező.

Paraméterdokumentáció

Az alábbi táblázat felsorolja a függvényparaméterek metaadataiban beállítható dokumentációs mezőket. A mezők egyike sem kötelező.

Egyszerű példa

Az alábbi kódrészlet (és az eredményül kapott párbeszédpanelek) a HelloWorldWithDocs-mintából származnak.

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

Ez a kód a következő párbeszédpaneleket eredményezi a Power BI-ban.

Függvényhívás

Függvényadatok

Többsoros példa

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

Ez a kód (a kapcsolódó közzétételi információkkal stb.) a következő párbeszédet eredményezi a Power BI-ban. Az új vonalak a "#(lf)" vagy a "line feed" szövegben jelennek meg.