新增函式檔
Power Query 會根據函式的自變數自動為您產生調用 UI。 根據預設,此 UI 會包含函式的名稱,以及每個參數的輸入。
同樣地,評估函式的名稱,而不指定參數,將會顯示其相關信息。
您可能會注意到,內建函式通常會提供更佳的用戶體驗,並提供描述、工具提示,甚至是範例值。 您可以在函式類型上定義特定的中繼值,以利用這個相同的機制。 本主題描述 Power Query 所使用的中繼字段,以及如何在延伸模組中使用它們。
您可以定義自訂 類型 值,為您的函式提供檔。 此程式看起來像這樣:
- 定義每個參數的類型。
- 定義函式的類型。
- 將各種
Documentation.*
欄位新增至您的類型元數據記錄。 - 呼叫 Value.ReplaceType ,將類型指定為您的共用函式。
您可以在 M 語言規格中找到類型和元資料值的詳細資訊。
使用此方法可讓您提供函式的描述和顯示名稱,以及個別參數。 您也可以提供參數的範例值,以及定義預設值清單(將預設文字框控件轉換成下拉式清單)。
Power Query 體驗會使用對 Value.Type、Type.FunctionParameters 和 Value.Metadata 的呼叫組合,從函式類型的中繼值擷取檔。
下表列出可在函式元數據中設定的檔欄位。 所有欄位都是選擇性的。
欄位 | 類型 | 詳細資料 |
---|---|---|
Documentation.Examples | 清單 | 具有函式使用範例的記錄物件清單。 僅顯示為函式資訊的一部分。 每個記錄都應該包含下列選擇性文字欄位: Description 、 Code 和 Result 。 |
Documentation.LongDescription | text | 函式所執行之功能的完整描述,顯示在函式資訊中。 |
Documentation.Name | text | 要顯示在函式調用對話框頂端的文字。 |
下表列出可在函式參數元數據中設定的檔欄位。 所有欄位都是選擇性的。
欄位 | 類型 | 詳細資料 |
---|---|---|
Documentation.AllowedValues | 清單 | 此參數的有效值清單。 提供此欄位會將輸入從文字框變更為下拉式清單。 請注意,這不會防止使用者手動編輯查詢以提供替代值。 |
Documentation.FieldCaption | text | 要用於 參數的易記顯示名稱。 |
Documentation.FieldDescription | text | 顯示名稱旁要顯示的描述。 |
Documentation.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中的下列對話框。
函式調用
函式資訊
[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'。