FormattingModel ユーティリティ

[アーティクル]
11/30/2023

"書式設定モデルのユーティリティ" には、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 には、次の 2 つの主要なメソッドがあります。

    /**
     * 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];
}

書式設定カード

"書式設定カード" により、[書式] ペインまたは [分析] ペインで書式設定カードが指定されます。書式設定カードには、複数の書式設定スライス、コンテナー、グループ、およびプロパティを含めることができます。

書式設定カードにスライスを追加すると、これらすべてのスライスが 1 つの書式設定カードに配置されます。

カード、スライス、およびグループは、visible パラメーターを false (既定では true) に設定することで動的に非表示にすることができます。

analyticsPane パラメーターを true または false に設定することで、カードによって [書式] ペインまたは [分析] ペインを設定できます。

1 つの書式設定設定グループとスライスを含む、書式設定設定カードを宣言する例:

カード名は 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 
                }
            },
        }
    }
}

[書式設定] グループ

一部の書式設定カード内には、グループを含めることができます。グループはスライスで構成され、展開/折りたたむことができます。

1 つのスライスで書式設定設定グループを宣言する例:

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];
}

書式設定スライス

書式設定スライスの種類は、単純と複合の 2 種類のスライスで構成されます

各スライスには書式設定プロパティが含まれています。使用可能な書式設定プロパティの種類の長い一覧があります。

制限付き型 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,
            },
        }
    });