Hinzufügen der Funktionsdokumentation
Power Query generiert automatisch eine Aufrufbenutzeroberfläche für Sie basierend auf den Argumenten für Ihre Funktion. Standardmäßig enthält diese Benutzeroberfläche den Namen Ihrer Funktion und eine Eingabe für jeden Parameter.
Ebenso zeigt die Auswertung des Namens Ihrer Funktion ohne Angabe von Parametern Informationen dazu an.
Möglicherweise stellen Sie fest, dass integrierte Funktionen in der Regel eine bessere Benutzererfahrung mit Beschreibungen, QuickInfos und sogar Beispielwerten bieten. Sie können diesen Mechanismus nutzen, indem Sie bestimmte Metawerte für Ihren Funktionstyp definieren. In diesem Thema werden die Metafelder beschrieben, die von Power Query verwendet werden, und wie Sie sie in Ihren Erweiterungen verwenden können.
Funktionstypen
Sie können Dokumentation für Ihre Funktion bereitstellen, indem Sie benutzerdefinierte Typwerte definieren. Der Vorgang sieht folgendermaßen aus:
- Definieren Sie für jeden Parameter einen Typ.
- Definieren Sie einen Typ für Ihre Funktion.
- Fügen Sie Ihrem Metadatendatensatz verschiedene
Documentation.*
-Felder hinzu. - Rufen Sie Value.ReplaceType auf, um den Typ ihrer freigegebenen Funktion zu schreiben.
Weitere Informationen zu Typen und Metadatenwerten finden Sie in der M-Sprachspezifikation.
Mit diesem Ansatz können Sie Beschreibungen und Anzeigenamen für Ihre Funktion sowie einzelne Parameter angeben. Sie können auch Beispielwerte für Parameter angeben sowie eine vordefinierte Liste mit Werten definieren (indem Sie das Standard-Textfeld-Steuerelement in eine Dropdownliste umwandeln).
Die Power Query-Oberfläche ruft dokumentationen aus Metawerten für den Typ Ihrer Funktion mithilfe einer Kombination aus Aufrufen von Value.Type, Type.FunctionParameters und Value.Metadata ab.
Funktionsdokumentation
In der folgenden Tabelle sind die Dokumentationsfelder aufgeführt, die in den Metadaten für Ihre Funktion festgelegt werden können. Alle Felder sind optional.
Feld | type | Details |
---|---|---|
Documentation.Examples | Liste | Liste der Datensatzobjekte mit Beispielverwendung der Funktion. Nur als Teil der Funktionsinformationen angezeigt. Jeder Datensatz sollte die folgenden optionalen Textfelder enthalten: Description , , Code und Result . |
Documentation.LongDescription | Text | Vollständige Beschreibung der Funktion, die in den Funktionsinformationen angezeigt wird. |
Documentation.Name | Text | Text, der über dem oberen Rand des Funktionsaufrufdialogfelds angezeigt werden soll. |
Parameterdokumentation
In der folgenden Tabelle sind die Dokumentationsfelder aufgeführt, die in den Metadaten für Ihre Funktionsparameter festgelegt werden können. Alle Felder sind optional.
Feld | type | Details |
---|---|---|
Documentation.AllowedValues | Liste | Liste gültiger Werte für diesen Parameter. Wenn Sie dieses Feld angeben, wird die Eingabe aus einem Textfeld in eine Dropdownliste geändert. Beachten Sie, dass ein Benutzer die Abfrage nicht manuell bearbeiten kann, um alternative Werte zu liefern. |
Documentation.FieldCaption | Text | Benutzerfreundlicher Anzeigename, der für den Parameter verwendet werden soll. |
Documentation.FieldDescription | Text | Beschreibung, die neben dem Anzeigenamen angezeigt werden soll. |
Documentation.SampleValues | Liste | Liste der Beispielwerte, die im Textfeld angezeigt werden sollen (als ausgeblendeter Text). |
Formatting.IsMultiLine | boolean | Ermöglicht es Ihnen, eine mehrzeilige Eingabe zu erstellen, z. B. zum Einfügen in systemeigene Abfragen. |
Formatting.IsCode | boolean | Formatiert das Eingabefeld für Code, häufig mit mehrzeiligen Eingaben. Verwendet eine codeähnliche Schriftart anstelle der Standardschriftart. |
Einfaches Beispiel
Der folgende Codeausschnitt (und resultierende Dialogfelder) stammen aus dem HelloWorldWithDocs-Beispiel .
[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;
Dieser Code führt zu den folgenden Dialogfeldern in Power BI.
Funktionsaufruf
Funktionsinformationen
Mehrzeiliges Beispiel
[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);
Dieser Code (mit zugehörigen Veröffentlichungsinformationen usw.) führt zum folgenden Dialog in Power BI. Neue Zeilen werden im Text mit '#(lf)', oder 'Zeilenvorschub', dargestellt.