Funktiodokumentaation lisääminen

Power Query luo sinulle automaattisesti kutsukäyttöliittymän funktiosi argumenttien perusteella. Oletusarvoisesti tämä käyttöliittymä sisältää funktion nimen ja syötteen kullekin parametrille.

Vastaavasti funktion nimen arvioiminen ilman parametrien määrittämistä näyttää tietoja siitä.

Saatat huomata, että sisäiset funktiot tarjoavat yleensä paremman käyttökokemuksen, kuvaukset, työkaluvihjeet ja jopa malliarvot. Voit hyödyntää tätä samaa mekanismia määrittämällä tietyt meta-arvot funktion tyypille. Tässä aiheessa kuvataan Power Queryn käyttämiä metakenttiä ja sitä, miten voit hyödyntää niitä laajennuksissasi.

Funktiotyypit

Voit tarjota funktioillesi ohjeita määrittämällä mukautettuja tyyppiarvoja . Prosessi näyttää tältä:

1. Määritä kullekin parametrille tyyppi.
2. Määritä funktiolle tyyppi.
3. Lisää useita Documentation.* kenttiä tyyppiesi metatietotietueen.
4. Kutsu Value.ReplaceType-funktiota määrittämään jaetun funktion tyyppi.

M-kielen määrityksestä saat lisätietoja tyypeistä ja metatietoarvoista.

Tämän lähestymistavan avulla voit antaa funktiollesi kuvauksia ja näyttönimiä sekä yksittäisiä parametreja. Voit myös antaa parametrien malliarvot sekä määrittää esiasetetun arvoluettelon (muuttamalla oletustekstiruutu-ohjausobjektin avattavaksi luetteloksi).

Power Query -käyttökokemus noutaa funktion tyypin meta-arvoista value.Type-, Type.FunctionParameters- ja Value.Metadata-kutsujen yhdistelmällä.

Funktiodokumentaatio

Seuraavassa taulukossa on lueteltu Dokumentaatio-kentät, jotka voidaan määrittää funktion metatiedoissa. Kaikki kentät ovat valinnaisia.

Field	Tyyppi	Tiedot
Documentation.Examples	list	Luettelo tietueobjekteista, joissa on esimerkki funktion käytöstä. Näytetään vain osana funktion tietoja. Kunkin tietueen tulee sisältää seuraavat valinnaiset tekstikentät: Description, Codeja Result.
Documentation.LongDescription	teksti	Funktion toimintotoimintojen täydellinen kuvaus, joka näytetään funktion edellisten tietojen kohdassa.
Documentation.Name	teksti	Funktiokutsu-valintaikkunan yläosassa näytettävä teksti.

Parametridokumentaatio

Seuraavassa taulukossa on lueteltu Dokumentaatio-kentät, jotka voidaan määrittää funktioparametrien metatiedoissa. Kaikki kentät ovat valinnaisia.

Field	Tyyppi	Tiedot
Documentation.AllowedValues	list	Tämän parametrin kelvollisten arvojen luettelo. Jos tämä kenttä on käytössä, se muuttaa syötteen tekstiruudusta avattavaksi luetteloksi. Huomaa, että tämä ei estä käyttäjää muokkaamasta kyselyä manuaalisesti antaakseen vaihtoehtoisia arvoja.
Documentation.FieldCaption	teksti	Kutsumanimi parametrille.
Documentation.FieldDescription	teksti	Näyttönimen vieressä näytettävä kuvaus.
Documentation.SampleValues	list	Luettelo näytearvoista, jotka näytetään tekstiruudun sisällä (häivytettynä tekstinä).
Formatting.IsMultiLine	boolean	Tämän avulla voit luoda monirivisen syötteen, esimerkiksi alkuperäisten kyselyiden liittämiseen.
Formatting.IsCode	boolean	Muotoilee syötekentän koodia varten käyttäen usein monirivisyötteitä. Käyttää koodimuotoista fonttia vakiofontin sijaan.

Perusesimerkki

Seuraavat koodikatkelmat (ja tulokseksi saatavat valintaikkunat) ovat HelloWorldWithDocs-mallista.

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

Tämä koodi tuottaa seuraavat valintaikkunat Power BI:ssä.

Funktiokutsu

Funktion tiedot

Monirivinen esimerkki

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

Tämä koodi (johon liittyy julkaisutietoja ja niin edelleen) johtaa seuraavaan vuoropuheluun Power BI:ssä. Uudet rivit esitetään tekstinä #(lf)" tai "rivin syöte".