Menambahkan dokumentasi fungsi

Power Query akan secara otomatis menghasilkan UI pemanggilan untuk Anda berdasarkan argumen untuk fungsi Anda. Secara default, UI ini akan berisi nama fungsi Anda, dan input untuk setiap parameter Anda.

Demikian pula, mengevaluasi nama fungsi Anda, tanpa menentukan parameter, akan menampilkan informasi tentang fungsi tersebut.

Anda mungkin melihat bahwa fungsi bawaan biasanya memberikan pengalaman pengguna yang lebih baik, dengan deskripsi, tipsalat, dan bahkan nilai sampel. Anda dapat memanfaatkan mekanisme yang sama ini dengan menentukan nilai meta tertentu pada jenis fungsi Anda. Topik ini menjelaskan bidang meta yang digunakan oleh Power Query, dan bagaimana Anda bisa menggunakannya di ekstensi Anda.

Jenis Fungsi

Anda dapat menyediakan dokumentasi untuk fungsi Anda dengan menentukan nilai jenis kustom. Prosesnya terlihat seperti ini:

1. Tentukan jenis untuk setiap parameter.
2. Tentukan jenis untuk fungsi Anda.
3. Tambahkan berbagai Documentation.* bidang ke catatan metadata jenis Anda.
4. Panggil Value.ReplaceType untuk berlangganan jenis ke fungsi bersama Anda.

Anda dapat menemukan informasi selengkapnya tentang jenis dan nilai metadata dalam Spesifikasi Bahasa M.

Menggunakan pendekatan ini memungkinkan Anda untuk memberikan deskripsi dan nama tampilan untuk fungsi Anda, serta parameter individual. Anda juga dapat menyediakan nilai sampel untuk parameter, serta menentukan daftar nilai yang telah ditetapkan sebelumnya (mengubah kontrol kotak teks default menjadi menu drop-down).

Pengalaman Power Query mengambil dokumentasi dari nilai meta pada jenis fungsi Anda, menggunakan kombinasi panggilan ke Value.Type, Type.FunctionParameters, dan Value.Metadata.

Dokumentasi fungsi

Tabel berikut mencantumkan bidang Dokumentasi yang bisa diatur dalam metadata untuk fungsi Anda. Bidang-bidang ini bersifat opsional.

Bidang	Jenis	Detail
Documentation.Examples	list	Daftar objek rekaman dengan contoh penggunaan fungsi. Hanya ditampilkan sebagai bagian dari info fungsi. Setiap rekaman harus berisi bidang teks opsional berikut: Description, , Codedan Result.
Documentation.LongDescription	text	Deskripsi lengkap tentang apa yang dilakukan fungsi, ditampilkan dalam info fungsi.
Documentation.Name	text	Teks untuk ditampilkan di bagian atas dialog pemanggilan fungsi.

Dokumentasi parameter

Tabel berikut mencantumkan bidang Dokumentasi yang bisa diatur dalam metadata untuk parameter fungsi Anda. Bidang-bidang ini bersifat opsional.

Bidang	Jenis	Detail
Documentation.AllowedValues	list	Daftar nilai yang valid untuk parameter ini. Menyediakan bidang ini akan mengubah input dari kotak teks menjadi daftar drop-down. Perhatikan, ini tidak mencegah pengguna mengedit kueri secara manual untuk menyediakan nilai alternatif.
Documentation.FieldCaption	text	Nama tampilan yang mudah digunakan untuk parameter.
Documentation.FieldDescription	text	Deskripsi untuk ditampilkan di samping nama tampilan.
Documentation.SampleValues	list	Daftar nilai sampel yang akan ditampilkan (sebagai teks pudar) di dalam kotak teks.
Formatting.IsMultiLine	Boolean	Memungkinkan Anda membuat input multibaris, misalnya untuk menempelkan dalam kueri asli.
Formatting.IsCode	Boolean	Memformat bidang input untuk kode, umumnya dengan input multibaris. Menggunakan font seperti kode daripada font standar.

Contoh dasar

Cuplikan kode berikut (dan dialog yang dihasilkan) berasal dari sampel 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;

Kode ini menghasilkan dialog berikut di Power BI.

Pemanggilan fungsi

Info fungsi

Contoh multibaris

[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);

Kode ini (dengan informasi penerbitan terkait, dan sebagainya) menghasilkan dialog berikut di Power BI. Baris baru akan diwakili dalam teks dengan '#(lf)', atau 'umpan baris'.