Incorporación de documentación de funciones
Power Query generará automáticamente una interfaz de usuario de invocación basada en los argumentos de la función. De forma predeterminada, la interfaz de usuario contiene el nombre de la función y una entrada para cada uno de los parámetros.
De la misma forma, la evaluación del nombre de la función, sin especificar parámetros, muestra información sobre la misma.
Es posible que observe que las funciones integradas habitualmente brindan una mejor experiencia de usuario, con descripciones, información sobre herramientas e incluso valores de ejemplo. Es posible sacar provecho de este mismo mecanismo si se definen metadatos específicos sobre el tipo de función. Aquí se describen los campos de metadatos que usa Power Query y su uso en las extensiones.
Es posible proporcionar documentación para la función si se definen valores de tipo personalizados. El proceso tiene este aspecto:
- Defina un tipo para cada uno de los parámetros.
- Defina un tipo para la función.
- Añada varios campos
Documentation.*
al registro de metadatos de tipos. - Llame a Value.ReplaceType para la asignación del tipo a la función compartida.
Es posible encontrar más información acerca de los tipos y los valores de metadatos en la especificación Lenguaje M.
El uso de este enfoque permite brindar a la función descripciones y nombres para mostrar, así como parámetros individuales. También se pueden proporcionar valores de ejemplo para los parámetros, así como definir una lista preestablecida de valores (lo que convertirá el control de cuadro de texto predeterminado en una lista desplegable).
La experiencia Power Query recupera la documentación de los valores de metadatos del tipo de función a través de una combinación de llamadas a Value.Type, Type.FunctionParameters y Value.Metadata.
En la tabla a continuación se enumeran los campos de documentación que se pueden establecer en los metadatos de la función. Todos los campos son opcionales.
Campo | Tipo | Detalles |
---|---|---|
Documentation.Examples | list | Lista de objetos de registro con ejemplo de uso de la función. Solo se muestra como parte de la información de la función. Cada registro debe contener los siguientes campos de texto opcionales: Description , Code y Result . |
Documentation.LongDescription | text | Descripción completa respecto a la tarea de la función, que se muestra en la información de la misma. |
Documentation.Name | text | Texto que aparece en la parte superior del cuadro de diálogo de invocación de la función. |
En la tabla a continuación se enumeran los campos de documentación que se pueden establecer en los metadatos de los parámetros de función. Todos los campos son opcionales.
Campo | Tipo | Detalles |
---|---|---|
Documentation.AllowedValues | list | Lista de valores válidos para el parámetro. Si se rellena este campo, la entrada cambiará de un cuadro de texto a una lista desplegable. Observe que esto no impide que un usuario edite la consulta de forma manual para proporcionar valores alternativos. |
Documentation.FieldCaption | text | Nombre descriptivo para el parámetro. |
Documentation.FieldDescription | text | Descripción que aparece junto al nombre para mostrar. |
Documentation.SampleValues | list | Lista de valores de ejemplo que se mostrarán (en forma de texto atenuado) dentro del cuadro de texto. |
Format.IsMultiLine | boolean | Permite crear una entrada de más de una línea, por ejemplo, para pegar en consultas nativas. |
Format.IsCode | boolean | Da formato al campo de entrada para el código, por lo general con entradas de varias líneas. Utiliza una fuente similar a un código en lugar de la fuente estándar. |
El siguiente fragmento de código (y los diálogos obtenidos) procede del ejemplo 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;
El código da como resultado los cuadros de diálogo siguientes en Power BI.
function_invocation
Información de función
[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);
El código (con la información de publicación asociada, etc.) da como resultado el siguiente diálogo en Power BI. Las nuevas líneas se representarán en el texto con "#(lf)" o "avance de líneas".