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

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

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

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

Function Types

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

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

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

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

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

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

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

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

เอกสารพารามิเตอร์

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

เขตข้อมูล	ขนิด	คำอธิบาย
Documentation.AllowedValues	รายการ	รายการของค่าที่ถูกต้องสําหรับพารามิเตอร์นี้ การให้เขตข้อมูลนี้จะเปลี่ยนการป้อนข้อมูลจากกล่องข้อความเป็นรายการแบบดรอปดาวน์ หมายเหตุ การดําเนินการนี้ไม่ได้ป้องกันไม่ให้ผู้ใช้แก้ไขคิวรีด้วยตนเองเพื่อให้มีค่าอื่น
Documentation.FieldCaption	ข้อความ	ชื่อที่แสดงที่เรียกง่ายเพื่อใช้สําหรับพารามิเตอร์
Documentation.FieldDescription	ข้อความ	คําอธิบายที่จะแสดงถัดจากชื่อที่แสดง
Documentation.SampleValues	รายการ	รายการของค่าตัวอย่างที่จะแสดง (เป็นข้อความสีจาง) ภายในกล่องข้อความ
Formatting.IsMultiLine	แบบบูลีน	ช่วยให้คุณสามารถสร้างการป้อนข้อมูลหลายบรรทัด ตัวอย่างเช่น สําหรับการวางในคิวรีดั้งเดิม
Formatting.IsCode	แบบบูลีน	จัดรูปแบบเขตข้อมูลป้อนเข้าสําหรับโค้ด ซึ่งมักมีอินพุตหลายบรรทัด ใช้แบบอักษรที่เหมือนกับโค้ดแทนที่จะเป็นแบบอักษรมาตรฐาน

ตัวอย่างพื้นฐาน

ส่วนย่อยของโค้ดต่อไปนี้ (และกล่องโต้ตอบที่เป็นผลลัพธ์) มาจากตัวอย่าง 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)' หรือ 'line feed'