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에는 다음 두 가지 주요 메서드가 있습니다.

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