FormattingModel 公用程式

發行項
07/03/2024

「格式化模型公用程式」包含建置格式化設定模型以填入 Power BI 自訂視覺效果的屬性窗格 (格式和分析窗格) 所需的類別、介面和方法。

格式化設定服務

「格式化設定服務」接收格式化設定模型，並將其轉換成填入格式化窗格的格式化模型。格式化模型服務也支援字串當地語系化。

將格式化設定服務初始化：

import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";

export class MyVisual implements IVisual {
    // declaring formatting settings service 
    private formattingSettingsService: FormattingSettingsService;

    constructor(options: VisualConstructorOptions) {
        
        this.formattingSettingsService = new FormattingSettingsService();
        
        // ...
    }
}

格式化設定服務介面 IFormattingSettingsService 有兩個主要方法：

    /**
     * Build visual formatting settings model from metadata dataView
     * 
     * @param dataViews metadata dataView object
     * @returns visual formatting settings model 
     */
    populateFormattingSettingsModel<T extends Model>(typeClass: new () => T, dataViews: powerbi.DataView[]): T;

    /**
     * Build formatting model by parsing formatting settings model object 
     * 
     * @returns powerbi visual formatting model
     */
    buildFormattingModel(formattingSettingsModel: Model): visuals.FormattingModel;

格式化設定模型

「設定模型」包含並包裝格式化窗格和分析窗格的所有格式化卡片。

export class Model {
    cards: Array<Cards>;
}

此範例會宣告新的格式化設定模型：

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsCards = formattingSettings.Cards;
import FormattingSettingsModel = formattingSettings.Model;

export class VisualSettingsModel extends FormattingSettingsModel {
    // Building my visual formatting settings card
    myVisualCard: FormattingSettingsCompositeCard = new myVisualCardSettings();

    // Add formatting settings card to cards list in model
    cards: FormattingSettingsCards[] = [this.myVisualCard];
}

格式化設定卡片

「格式化設定卡片」指定格式化或分析窗格中的格式化卡片。格式化設定卡片可以包含多個格式化配量、容器、群組和屬性。

將配量新增至格式化設定卡片，會將所有這些配量放入一個格式化卡片中。

卡片、配量和群組可以動態隱藏，方法是將 visible 參數設定為 false (預設為 true)。

卡片可以透過將 analyticsPane 參數設定為 true 或 false 來填入格式化窗格或分析窗格。

以下示範如何宣告包含一個格式化設定群組和配量的格式化設定卡片：

卡片名稱應符合 capabilities.json 中的物件名稱
配量名稱應符合 capabilities.json 中的屬性名稱

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsGroup = formattingSettings.Group;
import FormattingSettingsSlice = formattingSettings.Slice;

// Formatting settings group
class myVisualGroupSettings extends FormattingSettingsGroup {
    // Formatting settings slice
    myAnotherNumericSlice = new formattingSettings.NumUpDown({
        name: "myAnotherNumericSlice",
        displayName: "My Formatting Numeric Slice in group",
        value: 15,
        visible: true,
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

// Formatting settings card
class myVisualCardSettings extends FormattingSettingsCompositeCard {
    // Formatting settings slice
    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 50,
        visible: true,
        options: {
            minValue: {
                type: powerbi.visuals.ValidatorType.Min,
                value: 0,
            },
            maxValue: {
                type: powerbi.visuals.ValidatorType.Max,
                value: 100,
            },
        }
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;

    groupSetting = new myVisualGroupSettings(Object())
    groups: Array<FormattingSettingsGroup> = [this.groupSetting]
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

capabilities.json 屬性宣告應為：

"objects": {
    "myVisualCard": {
        "properties": {
            "myNumericSlice": {
                "type": {
                    "numeric": true 
                }
            },
            "myAnotherNumericSlice": {
                "type": {
                    "numeric": true 
                }
            },
        }
    }
}

格式化設定群組

某些格式化設定卡片可以有內部群組。群組是由配量所組成，可以展開/摺疊。

以下示範如何宣告具有一個配量的格式化設定群組：

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsGroup = formattingSettings.Group;
import FormattingSettingsSlice = formattingSettings.Slice;

class myVisualGroupSettings extends FormattingSettingsGroup {
    myAnotherNumericSlice = new formattingSettings.NumUpDown({
        name: "myAnotherNumericSlice",
        displayName: "My Formatting Numeric Slice in group",
        value: 15,
        visible: true
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

格式化設定配量

格式化設定配量類型包含兩種配量類型 - 簡單與複合。

每個配量都包含格式化屬性。可用的格式化屬性類型清單很長。

以下示範如何宣告具有下列限制的 NumUpDown 類型格式化設定配量：

配量名稱應符合 capabilities.json 中的屬性名稱。

    import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 50,
        visible: true,
        options: {
            minValue: {
                type: powerbi.visuals.ValidatorType.Min,
                value: 0,
            },
            maxValue: {
                type: powerbi.visuals.ValidatorType.Max,
                value: 100,
            },
        }
    });

使用 FormattingModel 公用程式建置格式化窗格模型

開啟您的 settings.ts 檔案。
使用所有元件 (卡片、群組、配量、屬性...) 建置您自己的格式化設定模型，並將其命名為 VisualFormattingSettings。將您的設定程式碼取代如下：

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsSlice = formattingSettings.Slice;
import FormattingSettingsModel = formattingSettings.Model;

export class VisualSettingsModel extends FormattingSettingsModel {
    // Building my visual formatting settings card
    myVisualCard: FormattingSettingsCard = new myVisualCardSettings();

    // Add formatting settings card to cards list in model
    cards: Array<FormattingSettingsCompositeCard> = [this.myVisualCard];
}

class myVisualCardSettings extends FormattingSettingsCompositeCard {
    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 100,
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

在您的功能檔案中，新增您的格式化物件和屬性

"objects": {
    "myVisualCard": {
        "properties": {
            "myNumericSlice": {
                "type": {
                    "numeric": true 
                }
            }
        }
    }
}

在您的視覺效果類別中，匯入下列內容：

import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";
import { VisualFormattingSettingsModel } from "./settings";

宣告格式化設定和格式化設定服務

   private formattingSettings: VisualFormattingSettingsModel;
   private formattingSettingsService: FormattingSettingsService;

在建構函式中將格式化設定服務初始化

constructor(options: VisualConstructorOptions) {
    this.formattingSettingsService = new FormattingSettingsService();

    // ...
}

使用格式化設定服務 populateFormattingSettingsModel 在更新 API 中建置格式化設定

public update(options: VisualUpdateOptions) {
    this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews);
    // ...
}

建置格式化模型並在 getFormattingModel API 中傳回

public getFormattingModel(): powerbi.visuals.FormattingModel {
    return this.formattingSettingsService.buildFormattingModel(this.formattingSettings);
}

格式化屬性選取器

格式化屬性描述項中的選擇性選取器會決定 dataView 中每個屬性繫結的位置。有四個不同的選項。

您可以將選取器新增至格式化屬性的描述項物件中。此範例是使用屬性選取器，從色彩自訂視覺效果資料點的 SampleBarChart 所取得：

new formattingSettings.ColorPicker({
    name: "fill",
    displayName: dataPoint.category,
    value: { value: dataPoint.color },
    selector: dataViewWildcard.createDataViewWildcardSelector(dataViewWildcard.DataViewWildcardMatchingOption.InstancesAndTotals),
    altConstantSelector: dataPoint.selectionId.getSelector(),
    instanceKind: powerbi.VisualEnumerationInstanceKinds.ConstantOrRule
}

將設定重設為預設值

格式化模型公用程式可讓您將設定重設為預設值，方法是將所有格式化屬性描述項自動新增至功能的格式化卡片清單，以還原為預設描述項 revertToDefaultDescriptors。

您可以從下列位置重設格式化設定：

格式化卡片的 [重設為預設值] 按鈕
格式化窗格頂端列的 [將所有設定重設為預設值] 按鈕

當地語系化

如需當地語系化功能及設定當地語系化環境的詳細資訊，請參閱將當地語言新增至 Power BI 視覺效果。

如果自訂視覺效果需要當地語系化，請使用當地語系化管理員將格式化設定服務初始化：

constructor(options: VisualConstructorOptions) {

    const localizationManager = options.host.createLocalizationManager();
    this.formattingSettingsService = new FormattingSettingsService(localizationManager);
    
    // ...
}

每當您想要將字串當地語系化時，請在適當的格式化元件中新增 displayNameKey 或 descriptionKey，而不是 displayName 和 description。以下示範如何使用當地語系化的顯示名稱和描述建置格式化配量

 myFormattingSlice = new formattingSettings.NumUpDown({
        name: "myFormattingSlice",
        displayNameKey: "myFormattingSlice_Key",
        descriptionKey: "myFormattingSlice_DescriptionKey",
        value: 100
    });

應該將 displayNameKey 和 descriptionKey 值新增至 resources.json 檔案。

共用方式為