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:
- Tentukan jenis untuk setiap parameter.
- Tentukan jenis untuk fungsi Anda.
- Tambahkan berbagai
Documentation.*bidang ke catatan metadata jenis Anda. - 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'.
