การเพิ่มเอกสารประกอบฟังก์ชัน

Power Query จะสร้าง UI การเรียกใช้ให้คุณโดยอัตโนมัติตามอาร์กิวเมนต์สําหรับฟังก์ชันของคุณ โดยค่าเริ่มต้น UI นี้จะมีชื่อของฟังก์ชันของคุณ และอินพุตสําหรับพารามิเตอร์แต่ละตัวของคุณ

ในทํานองเดียวกัน การประเมินชื่อฟังก์ชันของคุณโดยไม่ระบุพารามิเตอร์จะแสดงข้อมูลเกี่ยวกับฟังก์ชันนั้น

คุณอาจสังเกตเห็นว่าฟังก์ชันที่มีอยู่แล้วภายในมักจะให้ประสบการณ์ผู้ใช้ที่ดีขึ้นพร้อมคําอธิบาย คําแนะนําเครื่องมือ และแม้แต่ค่าตัวอย่าง คุณสามารถใช้ประโยชน์จากกลไกเดียวกันนี้ได้โดยการกําหนดค่าเมตาเฉพาะในประเภทฟังก์ชันของคุณ หัวข้อนี้อธิบายเขตข้อมูลเมตาที่ใช้โดย Power Query และวิธีที่คุณสามารถใช้ประโยชน์จากเขตข้อมูลเหล่านั้นในส่วนขยายของคุณ

Function Types

คุณสามารถจัดเตรียมเอกสารประกอบสําหรับฟังก์ชันของคุณโดยการกําหนดค่า ชนิด ที่กําหนดเอง กระบวนการมีลักษณะดังนี้:

1. กําหนดชนิดสําหรับแต่ละพารามิเตอร์
2. กําหนดชนิดสําหรับฟังก์ชันของคุณ
3. เพิ่มฟิลด์ต่างๆ Documentation.* ลงในเรกคอร์ดเมตาดาต้าชนิดของคุณ
4. เรียก Value.ReplaceType เพื่อกําหนดชนิดให้กับฟังก์ชันที่ใช้ร่วมกันของคุณ

คุณสามารถค้นหาข้อมูลเพิ่มเติมเกี่ยวกับชนิดและค่าเมตาดาต้าได้ในข้อมูลจําเพาะของภาษา M

การใช้วิธีนี้ช่วยให้คุณสามารถระบุคําอธิบายและชื่อที่แสดงสําหรับฟังก์ชันของคุณ ตลอดจนพารามิเตอร์แต่ละตัว คุณยังสามารถระบุค่าตัวอย่างสําหรับพารามิเตอร์ ตลอดจนการกําหนดรายการค่าที่ตั้งไว้ล่วงหน้า (เปลี่ยนตัวควบคุมกล่องข้อความเริ่มต้นให้เป็นดรอปดาวน์)

ประสบการณ์การใช้งาน Power Query จะดึงเอกสารจากค่าเมตาเกี่ยวกับชนิดของฟังก์ชันของคุณ โดยใช้การเรียก Value.Type, Type.FunctionParameters และ Value.Metadata ร่วมกัน

เอกสารประกอบฟังก์ชัน

ตารางต่อไปนี้แสดงรายการฟิลด์เอกสารที่สามารถตั้งค่าในเมตาดาต้าสําหรับ ฟังก์ชันของคุณ ฟิลด์ทั้งหมดเป็นตัวเลือก

ฟิลด์	ประเภท	ราย ละเอียด
เอกสารตัวอย่าง	รายการ	รายการของออบเจ็กต์เรกคอร์ดพร้อมตัวอย่างการใช้ฟังก์ชัน แสดงเป็นส่วนหนึ่งของข้อมูลฟังก์ชันเท่านั้น แต่ละเรกคอร์ดควรมีฟิลด์ข้อความที่เลือกได้ต่อไปนี้: Description, , CodeและResult
Documentation.Long คําอธิบาย	SMS	คําอธิบายทั้งหมดเกี่ยวกับการทํางานของฟังก์ชัน ซึ่งแสดงในข้อมูลฟังก์ชัน
Documentation.Name	SMS	ข้อความที่จะแสดงที่ด้านบนของกล่องโต้ตอบการเรียกใช้ฟังก์ชัน

เอกสารประกอบพารามิเตอร์

ตารางต่อไปนี้แสดงรายการฟิลด์เอกสารที่สามารถตั้งค่าในเมตาดาต้าสําหรับ พารามิเตอร์ฟังก์ชันของคุณ ฟิลด์ทั้งหมดเป็นตัวเลือก

ฟิลด์	ประเภท	ราย ละเอียด
เอกสารประกอบ.ค่าที่อนุญาต	รายการ	รายการของค่าที่ถูกต้องสําหรับพารามิเตอร์นี้ การระบุฟิลด์นี้จะเปลี่ยนอินพุตจากกล่องข้อความเป็นรายการแบบหล่นลง โปรดทราบว่าสิ่งนี้ไม่ได้ป้องกันไม่ให้ผู้ใช้แก้ไขแบบสอบถามด้วยตนเองเพื่อระบุค่าทางเลือก
เอกสารประกอบ.FieldCaption	SMS	ชื่อที่แสดงที่จําง่ายเพื่อใช้สําหรับพารามิเตอร์
เอกสาร.FieldDescription	SMS	คําอธิบายที่จะแสดงถัดจากชื่อที่แสดง
เอกสารประกอบ.ค่าตัวอย่าง	รายการ	รายการของค่าตัวอย่างที่จะแสดง (เป็นข้อความจาง) ภายในกล่องข้อความ
การจัดรูปแบบ.IsMultiLine	boolean	ให้คุณสร้างอินพุตแบบหลายบรรทัด เช่น สําหรับการวางในแบบสอบถามดั้งเดิม
การจัดรูปแบบ.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

การเรียกใช้ฟังก์ชัน

ข้อมูลฟังก์ชัน

ตัวอย่างหลายบรรทัด

[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)' หรือ 'ฟีดบรรทัด'