Ajout de la documentation relative aux fonctions
Power Query génère automatiquement une interface utilisateur d’appel pour vous en fonction des arguments de votre fonction. Par défaut, cette interface utilisateur contient le nom de votre fonction et une entrée pour chacun de vos paramètres.
De même, l’évaluation du nom de votre fonction, sans spécifier de paramètres, affiche des informations sur celle-ci.
Vous remarquerez que les fonctions intégrées offrent généralement une meilleure expérience utilisateur, avec des descriptions, des info-bulles et même des exemples de valeurs. Vous pouvez tirer parti de ce même mécanisme en définissant des métadonnées spécifiques sur votre type de fonction. Cette rubrique décrit les champs méta utilisés par Power Query et comment vous pouvez les utiliser dans vos extensions.
Types de fonctions
Vous pouvez fournir de la documentation pour votre fonction en définissant des valeurs de type personnalisées. Le processus se présente comme suit :
- Définissez un type pour chaque paramètre.
- Définissez un type pour votre fonction.
- Ajoutez différents champs
Documentation.*
à votre enregistrement de métadonnées de types. - Appelez Value.ReplaceType pour attribuer le type à votre fonction partagée.
Vous trouverez plus d’informations sur les valeurs de types et de métadonnées dans Spécification du langage M.
L’utilisation de cette approche vous permet de fournir des descriptions et des noms d’affichage pour votre fonction, ainsi que des paramètres individuels. Vous pouvez également fournir des exemples de valeurs pour les paramètres et définir une liste prédéfinie de valeurs (transformer le contrôle de zone de texte par défaut en liste déroulante).
L’expérience Power Query récupère la documentation des métadonnées sur le type de votre fonction, à l’aide d’une combinaison d’appels à Value.Type, Type.FunctionParameters et Value.Metadata.
Documentation relative aux fonctions
Le tableau suivant répertorie les champs de documentation qui peuvent être définis dans les métadonnées de votre fonction. Tous les champs sont facultatifs.
Champ | Type | Détails |
---|---|---|
Documentation.Examples | list | Liste des objets d’enregistrement avec exemple d’utilisation de la fonction. Affichée uniquement dans les cadre des informations relatives à la fonction. Chaque enregistrement doit contenir les champs de texte facultatifs suivants : Description , Code et Result . |
Documentation.LongDescription | texte | Description complète de ce que fait la fonction, affichée dans les informations relatives à la fonction. |
Documentation.Name | texte | Texte à afficher en haut de la boîte de dialogue d’appel de la fonction. |
Documentation relative aux paramètres
Le tableau suivant répertorie les champs de documentation qui peuvent être définis dans les métadonnées de vos paramètres de fonction. Tous les champs sont facultatifs.
Champ | Type | Détails |
---|---|---|
Documentation.AllowedValues | list | Liste de valeurs valides pour ce paramètre. Le remplissage de ce champ transforme l’entrée d’une zone de texte en liste déroulante. Notez que cela n’empêche pas un utilisateur de modifier manuellement la requête pour fournir d’autres valeurs. |
Documentation.FieldCaption | texte | Nom d’affichage convivial à utiliser pour le paramètre. |
Documentation.FieldDescription | texte | Description à afficher en regard du nom d’affichage. |
Documentation.SampleValues | list | Liste des exemples de valeurs à afficher (en tant que texte estompé) à l’intérieur de la zone de texte. |
Formatting.IsMultiLine | booléen | Vous permet de créer une entrée multiligne, par exemple pour coller dans des requêtes natives. |
Formatting.IsCode | booléen | Met en forme le champ d’entrée pour le code, généralement avec des entrées multilignes. Utilise une police de type code plutôt que la police standard. |
Exemple de base
L’extrait de code suivant (et les dialogues résultants) provient de l’exemple 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;
Ce code génère les boîtes de dialogue suivantes dans Power BI.
Invocation de la fonction
Informations sur la fonction
Exemple multiligne
[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);
Ce code (avec les informations de publication associées, et ainsi de suite) entraîne la boîte de dialogue suivante dans Power BI. Les nouvelles lignes seront représentées dans le texte avec « #(lf) » ou « line feed ».