在 Power BI 自訂視覺效果中自訂格式窗格
從 API 5.1 版開始，開發人員可以建立使用新 Power 格式窗格 的 視覺效果。 開發人員可以定義自訂視覺效果中任何屬性的卡片及其類別，讓報表建立者更容易使用這些視覺效果。
新的 API 會使用 FormattingModel 方法來自訂格式和分析窗格的部分。
提示
方法 getFormattingModel 會 enumerateObjectInstances 取代舊版 API 中的 方法。
會 getFormattingModel 傳 FormattingModel 回 ，定義視覺效果的格式化和分析窗格的外觀。
除了所有舊的格式化窗格功能之外， 新的格式化模型 還支援新的格式窗格功能、新屬性和新階層。
若要升級至 API 5.1+版，請將 pbiviz.json 檔案中的 設定 apiVersion 為 5.1 或更新版本，然後執行 下列其中一項 ：
- 使用 formattingmodel util 。 （ 建議 ）
- 如果沒有此公用程式，請根據下列方法只使用 API。
建立支援新格式窗格的視覺效果
若要建立使用新格式窗格的自訂視覺效果：
在 capabilities.json 檔案中 定義所有可
objects自訂的 。
每個物件都需要下列屬性：- 物件名稱
- 屬性名稱
- 屬性類型
所有其他屬性，包括
DisplayName和description現在都是選擇性的。建置自訂視覺效果 FormattingModel 。 定義自訂視覺格式模型的屬性，並使用程式碼來建置它（而非 JSON）。
getFormattingModel在傳回自訂視覺格式模型的自訂視覺類別中實作 API。 （此 API 取代enumerateObjectInstances了在舊版中使用的 。
對應格式設定屬性
如果您有使用舊版 API 建立的自訂視覺效果，而且想要移轉至新的格式窗格，或如果您要建立新的自訂視覺效果：
apiVersion將 pbiviz.json 檔案中的 設定為5.1或更新版本。針對 capabilities.json 中的每個 物件名稱和屬性名稱，建立相符的格式設定屬性。 格式化屬性應該有包含 的描述元，
objectName且propertyName符合 capabilities.json 中的 物件名稱和屬性名稱。
objects功能檔中的屬性仍然具有相同的格式，而且不需要變更。
例如，如果 circle capabilities.json 檔案中的 物件定義如下：
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
模型中的格式設定屬性應為 類型 ColorPicker ，如下所示：
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
如果下列其中一個條件成立，您會收到錯誤：
- 功能檔中的物件或屬性名稱與格式化模型中的物件或屬性名稱不符
- 功能檔中的屬性類型與格式化模型中的類型不符
格式化模型
格式化模型是您描述和自訂格式窗格的所有屬性的位置。
格式化模型元件
在新的格式化模型中，屬性元件會分組在邏輯類別和子類別中。 這些群組可讓模型更容易掃描。 有五個基本元件，從最大到最小：
格式化模型
用於格式化窗格前端介面的最大窗格容器。 其中包含格式化卡片的清單。格式化卡片
格式化屬性的最上層屬性群組容器。 每個卡片都包含一或多個格式群組，如下所示。
格式化群組
次要層級屬性群組容器。 格式化群組會顯示為格式化配量的群組容器。
格式化配量
屬性容器。 配量有兩種類型：- 簡單配量：個別屬性容器
- 複合配量 ：多個相關屬性容器分組成一個格式化配量
下圖顯示不同類型的配量。 「字型」是包含字型系列、大小和粗體、斜體和底線切換的複合配量。 「色彩」、「顯示單位」和其他配量都是簡單的配量，每個元件各有一個元件。
視覺效果窗格格式設定屬性
格式化模型中的每個屬性都應該符合 capabilities.json 檔案中的 和 物件類型。
下表顯示 capabilities.json 檔案中的 格式化屬性類型，以及其在新式格式化模型屬性中的相符類型類別：
| 類型 | 功能數值型別 | Formatting 屬性 |
|---|---|---|
| 布林值 | Bool | ToggleSwitch |
| 數值 | ||
| 列舉清單 | enumeration：[] | |
| 色彩 | 填滿 | ColorPicker |
| 梯度 | FillRule | GradientBar：屬性值應該是由下列專案組成的字串： minValue[,midValue],maxValue |
| Text | Text |
功能格式化物件
| 類型 | 功能數值型別 | Formatting 屬性 |
|---|---|---|
| 字型大小 | FontSize | NumUpDown |
| 字型家族 | FontFamily | FontPicker |
| 線條對齊 | 對齊方式 | AlignmentGroup |
| 標籤顯示單位 | LabelDisplayUnits | AutoDropDown |
* 列舉清單格式屬性在格式化模型和功能檔中不同。
在格式化設定類別中宣告下列屬性，包括列舉專案清單：
- ItemDropdown
- ItemFlagsSelection
在格式化設定類別中宣告下列屬性，而不需列舉專案清單。 在適當的 物件下，在 capabilities.json 中 宣告其列舉專案清單。 （這些類型與先前的 API 版本相同）：
- AutoDropdown
- AutoFlagSelection
複合配量屬性
格式化複合配量是包含多個相關屬性的格式化配量。
目前我們有兩種複合配量類型：
FontControl
這樣會將所有字型相關的屬性保持在一起。 它包含下列屬性：- 字型家族
- 字型大小
- 粗體 [選擇性]
- 斜體 [選擇性]
- 底線 [選擇性]
這些功能檔案中每個屬性都應該有對應的 物件：
屬性 功能類型 格式化類型 字型家族 格式設定： { fontFamily} FontPicker 字型大小 格式設定： {fontSize} NumUpDown 粗體 Bool ToggleSwitch Italic Bool ToggleSwitch 底線 Bool ToggleSwitch MarginPadding Margin 填補決定視覺效果中文字的對齊方式。 它包含下列屬性：
- Left
- Right
- 前幾個
- 下方
這些功能檔案中每個屬性都應該有對應的 物件：
屬性 功能類型 格式化類型 Left 數值 NumUpDown Right 數值 NumUpDown 前幾個 數值 NumUpDown 下方 數值 NumUpDown
範例：格式化數據卡
在此範例中，我們會示範如何使用一張卡片來建置自訂視覺效果格式模型。
卡片有兩個群組：
- 具有一個複合屬性的字型控制項群組
- 字型控制項
- 具有兩個簡單屬性的資料設計群組
- 字型色彩
- 線條對齊
首先，將物件新增至功能檔案：
"objects": {
"dataCard": {
"properties": {
"displayUnitsProperty": {
"type":
{
"formatting": {
"labelDisplayUnits": true
}
}
},
"fontSize": {
"type": {
"formatting": {
"fontSize": true
}
}
},
"fontFamily": {
"type": {
"formatting": {
"fontFamily": true
}
}
},
"fontBold": {
"type": {
"bool": true
}
},
"fontUnderline": {
"type": {
"bool": true
}
},
"fontItalic": {
"type": {
"bool": true
}
},
"fontColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"lineAlignment": {
"type": {
"formatting": {
"alignment": true
}
}
}
}
}
}
然後，建立 getFormattingModel
public getFormattingModel(): powerbi.visuals.FormattingModel {
// Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
let dataCard: powerbi.visuals.FormattingCard = {
description: "Data Card Description",
displayName: "Data Card",
uid: "dataCard_uid",
groups: []
}
// Building formatting group "Font Control Group"
// Notice that "descriptor" objectName and propertyName should match capabilities object and property names
let group1_dataFont: powerbi.visuals.FormattingGroup = {
displayName: "Font Control Group",
uid: "dataCard_fontControl_group_uid",
slices: [
{
uid: "dataCard_fontControl_displayUnits_uid",
displayName:"display units",
control: {
type: powerbi.visuals.FormattingComponent.Dropdown,
properties: {
descriptor: {
objectName: "dataCard",
propertyName:"displayUnitsProperty"
},
value: 0
}
}
},
// FontControl slice is composite slice, It means it contain multiple properties inside it
{
uid: "data_font_control_slice_uid",
displayName: "Font",
control: {
type: powerbi.visuals.FormattingComponent.FontControl,
properties: {
fontFamily: {
descriptor: {
objectName: "dataCard",
propertyName: "fontFamily"
},
value: "wf_standard-font, helvetica, arial, sans-serif"
},
fontSize: {
descriptor: {
objectName: "dataCard",
propertyName: "fontSize"
},
value: 16
},
bold: {
descriptor: {
objectName: "dataCard",
propertyName: "fontBold"
},
value: false
},
italic: {
descriptor: {
objectName: "dataCard",
propertyName: "fontItalic"
},
value: false
},
underline: {
descriptor: {
objectName: "dataCard",
propertyName: "fontUnderline"
},
value: false
}
}
}
}
],
};
// Building formatting group "Font Control Group"
// Notice that "descriptor" objectName and propertyName should match capabilities object and property names
let group2_dataDesign: powerbi.visuals.FormattingGroup = {
displayName: "Data Design Group",
uid: "dataCard_dataDesign_group_uid",
slices: [
// Adding ColorPicker simple slice for font color
{
displayName: "Font Color",
uid: "dataCard_dataDesign_fontColor_slice",
control: {
type: powerbi.visuals.FormattingComponent.ColorPicker,
properties: {
descriptor:
{
objectName: "dataCard",
propertyName: "fontColor"
},
value: { value: "#01B8AA" }
}
}
},
// Adding AlignmentGroup simple slice for line alignment
{
displayName: "Line Alignment",
uid: "dataCard_dataDesign_lineAlignment_slice",
control: {
type: powerbi.visuals.FormattingComponent.AlignmentGroup,
properties: {
descriptor:
{
objectName: "dataCard",
propertyName: "lineAlignment"
},
mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
value: "right"
}
}
},
]
};
// Add formatting groups to data card
dataCard.groups.push(group1_dataFont);
dataCard.groups.push(group2_dataDesign);
// Build and return formatting model with data card
const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
return formattingModel;
}
以下是產生的窗格：
將設定重設為預設值
新的格式窗格可以選擇將所有格式化卡片屬性值重設為預設值，方法是按一下 開啟卡片中顯示的 [重設為預設 ] 按鈕。
若要啟用這項功能，請將格式化卡片屬性描述項的清單新增至格式化卡片 revertToDefaultDescriptors 。
下列範例示範如何將重設新增 至預設 按鈕：
let dataCard: powerbi.visuals.FormattingCard = {
displayName: "Data Card",
// ... card parameters and groups list
revertToDefaultDescriptors: [
{
objectName: "dataCard",
propertyName:"displayUnitsProperty"
},
{
objectName: "dataCard",
propertyName: "fontFamily"
},
// ... the rest of properties descriptors
]
};
新增 revertToDefaultDescriptors 至格式化卡片也可以按一下 格式窗格頂端列中的 [將所有設定重設為預設 ] 按鈕，一次重設所有格式化卡片屬性：
格式化屬性選取器
格式化屬性描述元中的選擇性選取器會決定 dataView 中每個屬性系結的位置。 有四個不同的選項。 在物件選取器類型 中 閱讀它們。
當地語系化
如需當地語系化功能及設定當地語系化環境的詳細資訊，請參閱 將本機語言新增至 Power BI 視覺效果 使用當地語系化管理員將您想要當地語系化的元件格式化：
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
若要當地語系化格式化模型公用程式 格式化公用程式當地語系化 。
GitHub 資源
您可以在 GitHub - microsoft/powerbi-visuals-api 中找到 所有格式化模型介面：「formatting-model-api.d.ts」 中的 Power BI 自訂視覺效果 API
我們建議在 GitHub 使用新的格式化模型公用程式 - microsoft/powerbi-visuals-utils-formattingmodel：Power BI 視覺效果格式化模型協助程式公用程式
您可以在 GitHub 找到使用 API 5.1.0 版的自訂視覺效果 SampleBarChart 範例，並使用
getFormattingModelGitHub - microsoft/PowerBI-visuals-sampleBarChart：橫條圖自訂視覺效果進行教學課程 。
相關內容
更多問題嗎？ 詢問Power BI 社群
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應