FormattingModel utils

Cikk
12/22/2024

A formázási modell utils tartalmazza a Formázási beállítások modell létrehozásához szükséges osztályokat, felületeket és metódusokat a Power BI egyéni vizualizáció tulajdonságpaneljeinek (formátum- és elemzési paneljeinek) feltöltéséhez.

Formázási beállítások szolgáltatás

A formázási beállítások szolgáltatás megkapja a formázási beállítások modelljét, és egy formázási modellté alakítja, amely feltölti a formázási panelt. A formázási modellszolgáltatás a sztringek honosítását is támogatja.

A formázási beállítások szolgáltatás inicializálása:

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();
        
        // ...
    }
}

A Formázási beállítások szolgáltatás felületének IFormattingSettingsService két fő módszere van:

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

Formázási beállítások modellje

A beállításmodell tartalmazza és körbefuttatja a formázási és elemzési panel összes formázási kártyáját.

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

Ez a példa egy új formázási beállításmodellt deklarál:

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

Formázási beállítások kártyája

A formázási beállítások kártyája egy formázási kártyát határoz meg a formázási vagy elemzési panelen. A formázási beállítások kártyája több formázási szeletet, tárolót, csoportot és tulajdonságot tartalmazhat.

Ha szeleteket ad hozzá a formázási beállítások kártyához, az összes szeletet egy formázási kártyára helyezi.

A kártyák, szeletek és csoportok dinamikusan rejthetők el, ha a visible paramétert hamisra állítja (alapértelmezés szerint igaz).

A kártya kitöltheti a formázási vagy elemzési panelt a analyticsPane paraméter igaz vagy hamis értékre állításával.

Példa a formázási beállítások kártya deklarálására, beleértve egy formázási beállításcsoportot és szeletet:

A kártya nevének meg kell egyeznie a capabilities.json objektum nevével
A szelet nevének meg kell egyeznie a tulajdonság nevével a 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];
}

A capabilities.json tulajdonságdeklarációnak a következőnek kell lennie:

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

Formázási beállítások csoport

Egyes formázási beállítások kártyáiban lehetnek csoportok. A csoportok szeletekből állnak, és kibonthatók/összecsukhatók.

Példa a formázási beállítások csoport egy szeletel történő deklarálására:

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

Formázási beállítások szelete

A formázási beállítások szelettípusa két szelettípusból áll : egyszerű és összetett.

Minden szelet formázási tulajdonságokat tartalmaz. A rendelkezésre álló formázási tulajdonságok hosszú listája található.

Példa a formázási beállítások típusszeletének NumUpDown korlátozásokkal történő deklarálására:

A szelet nevének meg kell egyeznie capabilities.json tulajdonságnevével.

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

Formázási panelmodell létrehozása a FormattingModel Utils használatával

Nyissa meg a settings.ts fájlt.
Saját formázási beállításokat tartalmazó modellt hozhat létre az összes összetevőjével (kártyák, csoportok, szeletek, tulajdonságok ...), és nevezze el.VisualFormattingSettings Cserélje le a beállítások kódját a következőre:

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

A képességfájlban adja hozzá a formázási objektumokat és tulajdonságokat

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

A vizualizációs osztályban importálja a következőket:

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

Formázási beállítások és formázási beállítások deklarálása szolgáltatás

   private formattingSettings: VisualFormattingSettingsModel;
   private formattingSettingsService: FormattingSettingsService;

A formázási beállítások szolgáltatás inicializálása a konstruktorban

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

    // ...
}

Formázási beállítások létrehozása az Update API-ban a Formázási beállítások szolgáltatással populateFormattingSettingsModel

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

Formázási modell létrehozása és visszaadja az API-ban getFormattingModel

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

Formázási tulajdonságválasztó

A formázási tulajdonságok leírójának választható választója határozza meg, hogy az egyes tulajdonságok hol vannak kötve a dataView-ban. Négy különböző lehetőség közül választhat.

A leíró objektumban lévő formázási tulajdonsághoz választót is hozzáadhat. Ez a példa az egyéni vizualizációk adatpontjainak színezésére szolgáló SampleBarChart elemből származik a tulajdonságválasztók használatával:

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
}

Beállítások visszaállítása alapértelmezettre

A formázási modell segítségével alaphelyzetbe állíthatja a beállításokat az alapértelmezett értékre, ha automatikusan hozzáadja az összes formázási tulajdonságleírót a formázási kártya azon funkcióinak listájához, amelyeket vissza szeretne állítani az alapértelmezett leírókhoz revertToDefaultDescriptors.

A formázási beállítások alaphelyzetbe állítását a következő helyről engedélyezheti:

A formázási kártya alaphelyzetbe állítása az alapértelmezett gombra
A formázási panel felső sávja az összes beállítást alaphelyzetbe állítja az alapértelmezett gombra

Honosítás

A honosítási funkcióról és a honosítási környezet beállításáról további információt a Helyi nyelv hozzáadása a Power BI-vizualizációhoz című témakörben talál.

Init formatting settings service with localization manager abban az esetben, ha honosításra van szükség az egyéni vizualizációban:

constructor(options: VisualConstructorOptions) {

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

Adja hozzá displayNameKey vagy descriptionKeydisplayName használja a megfelelő formázási description összetevőt, amikor egy sztring honosítását szeretné. Példa formázási szelet létrehozására honosított megjelenítendő névvel és leírással

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

displayNameKey és descriptionKey értékeket kell hozzáadni a fájlokhoz resources.json .

Megosztás a következőn keresztül: