FormattingModel utils

项目
11/08/2023

格式设置模型 utils 包含生成格式化设置模型所需的类、接口和方法，以填充 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 Utils 生成格式设置窗格模型

打开 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
}

将设置重置为默认值

使用格式设置模型 utils，你可以通过自动将所有格式设置属性描述符添加到格式设置卡功能列表中以还原到默认描述符，从而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 文件中。

通过