Добавление документации по функциям

Статья
08/29/2023

Power Query автоматически создает пользовательский интерфейс вызова для вас на основе аргументов функции. По умолчанию этот пользовательский интерфейс будет содержать имя функции и входные данные для каждого из параметров.

DefaultFunctionPrompt.

Аналогичным образом, при вычислении имени функции без указания параметров будут отображаться сведения об этом.

DefaultFunctionInfo.

Вы можете заметить, что встроенные функции обычно обеспечивают лучший пользовательский интерфейс, с описаниями, подсказками и даже примерами значений. Вы можете воспользоваться этим же механизмом, определив определенные мета-значения в типе функции. В этом разделе описываются метаданные, используемые Power Query, и способы их использования в расширениях.

CsvDocument.

Типы функций

Вы можете предоставить документацию для функции, определив значения настраиваемых типов . Процесс выглядит следующим образом:

Определите тип для каждого параметра.
Определите тип для функции.
Добавьте различные Documentation.* поля в запись метаданных типов.
Вызовите Value.ReplaceType , чтобы писать тип в общую функцию.

Дополнительные сведения о типах и значениях метаданных см. в спецификации языка M.

С помощью этого подхода можно указать описания и отображаемые имена для функции, а также отдельные параметры. Вы также можете указать примеры значений для параметров, а также определить предустановленный список значений (превратив элемент управления текстового поля по умолчанию в раскрывающийся список).

Интерфейс Power Query извлекает документацию из метаданных типа функции, используя сочетание вызовов Value.Type, Type.FunctionParameters и Value.Metadata.

Документация по функциям

В следующей таблице перечислены поля документации, которые можно задать в метаданных для функции. Все поля здесь необязательные.

Поле	Тип	Сведения
Документация.Примеры	список	Список объектов записей с примером использования функции. Отображается только в составе сведений о функции. Каждая запись должна содержать следующие необязательные текстовые поля: `Description`, `Code`и `Result`.
Документация.LongDescription	text	Полное описание того, что делает функция, отображаемая в сведениях о функции.
Documentation.Name	text	Текст для отображения в верхней части диалогового окна вызова функции.

Документация по параметрам

В следующей таблице перечислены поля документации, которые можно задать в метаданных для параметров функции. Все поля здесь необязательные.

Поле	Тип	Сведения
Документация.AllowedValues	список	Список допустимых значений для этого параметра. Если это поле изменит входные данные из текстового поля в раскрывающийся список. Обратите внимание, что это не позволяет пользователю вручную изменять запрос для предоставления альтернативных значений.
Документация.FieldCaption	text	Понятное отображаемое имя, используемое для параметра.
Документация.FieldDescription	text	Описание, отображаемое рядом с отображаемым именем.
Документация.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)" или "каналом строк".

Построитель входных данных с несколькими строками.

Поделиться через