Προσθήκη τεκμηρίωσης συνάρτησης

Το Power Query θα δημιουργήσει αυτόματα ένα περιβάλλον εργασίας χρήστη κλήσης για εσάς με βάση τα ορίσματα για τη συνάθεσή σας. Από προεπιλογή, αυτό το περιβάλλον εργασίας χρήστη θα περιέχει το όνομα της συνάρτησης και μια είσοδο για κάθε μία από τις παραμέτρους σας.

Παρομοίως, η αξιολόγηση του ονόματος της συνάκρισής σας, χωρίς να καθοριστούν παράμετροι, θα εμφανίσει πληροφορίες σχετικά με αυτή.

Ενδέχεται να παρατηρήσετε ότι οι ενσωματωμένες συναρτήσεις συνήθως παρέχουν μια καλύτερη εμπειρία χρήστη, με περιγραφές, συμβουλές εργαλείων και ακόμη και δείγματα τιμών. Μπορείτε να αξιοποιήσετε αυτόν τον ίδιο μηχανισμό ορίζοντας συγκεκριμένες μετα-τιμές στον τύπο συνάρτησης. Αυτό το θέμα περιγράφει τα μετα-πεδία που χρησιμοποιούνται από το Power Query και πώς μπορείτε να τα χρησιμοποιήσετε στις επεκτάσεις σας.

Τύποι συναρτήσεων

Μπορείτε να παρέχετε τεκμηρίωση για τη συνάκρισή σας ορίζοντας τιμές προσαρμοσμένου τύπου . Η διαδικασία μοιάζει κάπως έτσι:

1. Καθορίστε έναν τύπο για κάθε παράμετρο.
2. Καθορίστε έναν τύπο για τη συνάκρισή σας.
3. Προσθέστε διάφορα Documentation.* πεδία στην εγγραφή μετα-δεδομένων των τύπων σας.
4. Καλέστε τη Value.ReplaceType για να αποδώσω τον τύπο στην κοινόχρηστη συνάρτηση.

Μπορείτε να βρείτε περισσότερες πληροφορίες σχετικά με τους τύπους και τις τιμές μετα-δεδομένων στην Προδιαγραφή γλώσσας M.

Η χρήση αυτής της προσέγγισης σάς επιτρέπει να παρέχετε περιγραφές και εμφανιζόμενα ονόματα για τη συνάρτηση, καθώς και μεμονωμένες παραμέτρους. Μπορείτε επίσης να παρέχετε δείγματα τιμών για τις παραμέτρους, καθώς και να ορίσετε μια προκαθορισμένη λίστα τιμών (μετατροπή του προεπιλεγμένου στοιχείου ελέγχου πλαισίου κειμένου σε αναπτυσσόμενη λίστα).

Η εμπειρία Power Query ανακτά την τεκμηρίωση από μετα-τιμές σχετικά με τον τύπο της συνάρτησης, χρησιμοποιώντας έναν συνδυασμό κλήσεων προς Value.Type, Type.FunctionParameters και Value.Metadata.

Τεκμηρίωση συνάρτησης

Ο παρακάτω πίνακας παραθέτει τα πεδία τεκμηρίωσης που μπορούν να οριστούν στα μετα-δεδομένα για τη συνάρτηση. Όλα τα πεδία είναι προαιρετικά.

Πεδίο	Τύπος	Details
Documentation.Examples	λίστα	Λίστα αντικειμένων εγγραφής με παράδειγμα χρήσης της συνάρτησης. Εμφανίζεται μόνο ως μέρος των πληροφοριών συνάρτησης. Κάθε εγγραφή θα πρέπει να περιέχει τα παρακάτω προαιρετικά πεδία κειμένου: Description, Codeκαι Result.
Documentation.LongDescription	κείμενο	Πλήρης περιγραφή του τι κάνει η συνάρτηση, η οποία εμφανίζεται στις πληροφορίες της συνάρτησης.
Documentation.Name	κείμενο	Κείμενο που εμφανίζεται στο επάνω μέρος του παραθύρου διαλόγου κλήσης συνάρτησης.

Τεκμηρίωση παραμέτρου

Ο παρακάτω πίνακας παραθέτει τα πεδία τεκμηρίωσης που μπορούν να οριστούν στα μετα-δεδομένα για τις παραμέτρους συναρτήσεων. Όλα τα πεδία είναι προαιρετικά.

Πεδίο	Τύπος	Details
Documentation.AllowedValues	λίστα	Λίστα έγκυρων τιμών για αυτή την παράμετρο. Με την προϋπόθεση ότι αυτό το πεδίο θα αλλάξει την είσοδο από ένα πλαίσιο κειμένου σε μια αναπτυσσόμενη λίστα. Σημειώστε ότι αυτό δεν εμποδίζει έναν χρήστη να επεξεργαστεί με μη αυτόματο τρόπο το ερώτημα για την παροχή εναλλακτικών τιμών.
Documentation.FieldCaption	κείμενο	Φιλικό εμφανιζόμενο όνομα που θα χρησιμοποιηθεί για την παράμετρο.
Documentation.FieldDescription	κείμενο	Περιγραφή που θα εμφανίζεται δίπλα στο εμφανιζόμενο όνομα.
Documentation.SampleValues	λίστα	Λίστα τιμών δείγματος που θα εμφανιστούν (ως σταδιακό κείμενο) μέσα στο πλαίσιο κειμένου.
Formatting.IsMultiLine	boolean	Σας επιτρέπει να δημιουργήσετε μια είσοδο πολλών γραμμών, για παράδειγμα για επικόλληση εγγενών ερωτημάτων.
Formatting.IsCode	boolean	Μορφοποιεί το πεδίο εισόδου για κώδικα, συνήθως με εισόδους πολλών γραμμών. Χρησιμοποιεί μια γραμματοσειρά τύπου κώδικα αντί για την τυπική γραμματοσειρά.

Βασικό παράδειγμα

Τα παρακάτω τμήματα κώδικα (και τα παράθυρα διαλόγου που προκύπτουν) προέρχονται από το δείγμα 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;

Αυτός ο κώδικας έχει ως αποτέλεσμα τα ακόλουθα παράθυρα διαλόγου στο Power BI.

Κλήση συνάρτησης

Πληροφορίες συνάρτησης

Παράδειγμα πολλών γραμμών

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

Αυτός ο κώδικας (με σχετικές πληροφορίες δημοσίευσης κ.ο.κ.) οδηγεί στο ακόλουθο παράθυρο διαλόγου στο Power BI. Οι νέες γραμμές θα αναπαρίστανται σε κείμενο με "#(lf)" ή "αλλαγή γραμμής".