添加函数文档

项目
10/05/2023

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

DefaultFunctionPrompt。

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

DefaultFunctionInfo。

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

CsvDocument。

函数类型

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

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

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

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

Power Query 体验将使用对 Value.Type、Type.FunctionParameters 和 Value.Metadata 调用组合从函数类型的元值中检索文档。

函数文档

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

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

参数文档

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

字段	类型	详细信息
Documentation.AllowedValues	列表	此参数的有效值列表。提供此字段会将输入从文本框更改为下拉列表。请注意，这不会阻止用户手动编辑查询以提供替代值。
Documentation.FieldCaption	text	用于参数的友好显示名称。
Documentation.FieldDescription	text	显示名称旁显示的说明。
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 中生成以下对话。

函数调用 FunctionPrompt。

函数信息 FunctionInfo。

多行示例

[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)”或表示为“换行符”。

多行输入生成器。

通过