Nástroje modelu formátování

Článek
10/31/2023

Nástroje pro formátování modelu obsahují třídy, rozhraní a metody potřebné k vytvoření modelu nastavení formátování pro naplnění podokna vlastností (formátová a analytická podokna) vlastního vizuálu Power BI.

Služba nastavení formátování

Služba nastavení formátování obdrží model nastavení formátování a převede ho na model formátování, který naplní podokno formátování. Služba modelu formátování podporuje také lokalizaci řetězců.

Inicializace služby nastavení formátování:

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

Formátování rozhraní rozhraní služby IFormatting Nastavení Service má dvě hlavní metody:

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

Model nastavení formátování

Model nastavení obsahuje a zabaluje všechny karty formátování pro podokno formátování a podokno analýzy.

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

Tento příklad deklaruje nový model nastavení formátování:

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

Karta Nastavení formátování

Karta nastavení formátování určuje kartu formátování v podokně formátování nebo analýzy. Karta nastavení formátování může obsahovat několik řezů formátování, kontejnerů, skupin a vlastností.

Přidání řezů na kartu nastavení formátování vloží všechny tyto řezy do jedné karty formátování.

Karty, řezy a skupiny se dají dynamicky skrývat nastavením parametru visible na false (ve výchozím nastavení true ).

Karta může naplnit podokno formátování nebo podokno analýzy nastavením parametru analyticsPane na hodnotu true nebo false.

Příklad deklarování karty nastavení formátování, včetně jedné skupiny nastavení formátování a řezu:

Název karty by se měl shodovat s názvem objektu v souboru capabilities.json.
Název řezu by se měl shodovat s názvem vlastnosti v souboru 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];
}

Deklarace vlastnosti capabilities.json by měla být:

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

Skupina nastavení formátování

Některé karty nastavení formátování můžou obsahovat skupiny uvnitř. Skupiny se skládají z řezů a dají se rozbalit nebo sbalit.

Příklad deklarace skupiny nastavení formátování s jedním řezem:

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

Řez nastavení formátování

Typ řezu nastavení formátování se skládá ze dvou typů řezů – jednoduchých a složených.

Každý řez obsahuje vlastnosti formátování. Existuje dlouhý seznam dostupných typů vlastností formátování.

Příklad deklarování řezu nastavení formátování typu NumUpDown s omezeními:

Název řezu by měl odpovídat názvu vlastnosti z 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,
            },
        }
    });

Vytvoření modelu podokna formátování pomocí nástrojů FormattingModel

Otevřete soubor settings.ts .
Vytvořte si vlastní model nastavení formátování se všemi jeho komponentami (karty, skupiny, řezy, vlastnosti ...) a pojmenujte ho VisualFormattingSettings. Nahraďte kód nastavení následujícím kódem:

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

Do souboru schopností přidejte objekty a vlastnosti formátování.

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

Ve třídě vizuálu naimportujte následující:

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

Deklarace nastavení formátování a služby nastavení formátování

   private formattingSettings: VisualFormattingSettingsModel;
   private formattingSettingsService: FormattingSettingsService;

Inicializace služby nastavení formátování v konstruktoru

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

    // ...
}

Vytváření nastavení formátování v rozhraní API pro aktualizaci pomocí služby nastavení formátování populateFormattingSettingsModel

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

Sestavení modelu formátování a jeho vrácení v getFormattingModel rozhraní API

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

Selektor vlastností formátování

Volitelný selektor v popisovači vlastností formátování určuje, kde každá vlastnost je svázána v objektu dataView. Existují čtyři různé možnosti.

Do vlastnosti formátování v objektu popisovače můžete přidat selektor. Tento příklad je převzat z SampleBarChart pro barevné vlastní vizuální datové body pomocí selektorů vlastností:

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
}

Obnovit výchozí nastavení

Nástroje pro formátování modelu vám umožní obnovit výchozí nastavení tím, že automaticky přidáte všechny vlastnosti formátování popisovače do seznamu karet formátování funkcí, které se mají obnovit na výchozí popisovače revertToDefaultDescriptors.

Nastavení formátování můžete resetovat z:

Výchozí tlačítko pro resetování karty formátování
Horní panel podokna formátování obnoví všechna nastavení na výchozí tlačítko.

Lokalizace

Další informace o funkci lokalizace a nastavení lokalizačního prostředí najdete v tématu Přidání místního jazyka do vizuálu Power BI.

Služba nastavení inicializačního formátování se správcem lokalizace v případě, že se lokalizace vyžaduje ve vlastním vizuálu:

constructor(options: VisualConstructorOptions) {

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

Pokaždé, když chcete lokalizovat řetězec, přidejte displayNameKey nebo descriptionKey ne displayName do description příslušné součásti formátování. Příklad vytvoření řezu formátování s lokalizovaným zobrazovaným názvem a popisem

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

displayNameKey a descriptionKey hodnoty by měly být přidány do resources.json souborů.

Sdílet prostřednictvím