添加函数文档

Power Query 将根据函数的参数自动生成调用 UI。 默认情况下，此 UI 将包含函数的名称以及每个参数的输入。

同样，在不指定参数的情况下评估函数的名称将显示有关它的信息。

你可能会注意到，内置函数通常提供更好的用户体验，并提供说明、工具提示，甚至示例值。 可以通过在函数类型上定义特定的元值来利用这一机制。 本主题介绍 Power Query 使用的元字段，以及如何在扩展中使用它们。

函数类型

可以通过定义自定义 类型 值来为函数提供文档。 此过程如下所示：

1. 为每个参数定义一个类型。
2. 定义函数的类型。
3. 将各种 Documentation.* 字段添加到类型元数据记录。
4. 调用 Value.ReplaceType 将类型归为共享函数。

可以在 M 语言规范中找到有关类型和元数据值的详细信息。

通过这种方法，您可以为函数及其各个参数提供说明和显示名称。 还可以为参数提供示例值，以及定义值的预设列表（将默认文本框控件转换为下拉列表）。

Power Query 功能通过调用组合 Value.Type、Type.FunctionParameters 和 Value.Metadata，从函数类型的元数据中检索文档。

函数文档

下表列出了可在 函数的元数据中设置的文档字段。 所有字段都是可选的。

领域	类型	详细信息
文档示例	列表	包含函数示例用法的记录对象列表。 仅显示为函数信息的一部分。 每个记录应包含以下可选文本字段： Description、 Code和 Result。
Documentation.LongDescription	文本消息	函数的功能的完整说明，显示在函数信息中。
文档.Name	文本消息	要显示在函数调用对话框顶部的文本。

参数文档

下表列出了可在 函数参数的元数据中设置的文档字段。 所有字段都是可选的。

领域	类型	详细信息
Documentation.AllowedValues	列表	此参数的有效值列表。 提供此字段会将输入从文本框更改为下拉列表。 请注意，这不会阻止用户手动编辑查询以提供替代值。
文档.字段标题	文本消息	用于参数的友好显示名称。
文档.字段描述	文本消息	用于显示名称旁的说明。
文档.示例值	列表	要在文本框中显示的示例值列表，以淡化文本形式呈现。
Formatting.IsMultiLine	布尔	允许您创建多行输入，例如用于粘贴本机查询。
Formatting.IsCode	布尔	设置代码输入字段的格式，通常情况下使用多行输入。 使用类似于代码的字体，而不是标准字体。

基本示例

以下代码片段（和生成的对话）来自 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)”或“换行符（line feed）”。