Narzędzia formatowaniaModel

Artykuł
10/31/2023

Narzędzia modelu formatowania zawierają klasy, interfejsy i metody potrzebne do utworzenia modelu ustawień formatowania w celu wypełnienia okienek właściwości (okienek formatowania i analizy) wizualizacji niestandardowej usługi Power BI.

Usługa ustawień formatowania

Usługa ustawień formatowania odbiera model ustawień formatowania i zamienia go w model formatowania, który wypełnia okienko formatowania. Usługa modelowania formatowania obsługuje również lokalizacje ciągów.

Inicjowanie usługi ustawień formatowania:

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

Formatowanie interfejsu IFormatowanie ustawień usługi Ustawienia Service ma dwie główne 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 ustawień formatowania

Model ustawień zawiera i opakowuje wszystkie karty formatowania dla okienka formatowania i okienka analizy.

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

W tym przykładzie zadeklarowany jest nowy model ustawień formatowania:

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 Ustawień formatowania

Karta ustawień formatowania określa kartę formatowania w okienku formatowania lub analizy. Karta ustawień formatowania może zawierać wiele wycinków formatowania, kontenerów, grup i właściwości.

Dodanie wycinków do karty ustawień formatowania powoduje przełączenie wszystkich tych wycinków na jedną kartę formatowania.

Karty, wycinki i grupy można ukrywać dynamicznie, ustawiając visible parametr na false (prawda domyślnie).

Karta może wypełnić okienko formatowania lub okienko analizy, ustawiając analyticsPane parametr na true lub false.

Przykład deklarowania karty ustawień formatowania, w tym jednej grupy ustawień formatowania i wycinka:

Nazwa karty powinna być zgodna z nazwą obiektu w pliku capabilities.json
Nazwa fragmentu powinna być zgodna z nazwą właściwości w pliku 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];
}

Deklaracja właściwości capabilities.json powinna być następująca:

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

Grupa ustawień formatowania

Niektóre karty ustawień formatowania mogą zawierać grupy wewnątrz. Grupy składają się z wycinków i można je rozwinąć/zwinąć.

Przykład deklarowania grupy ustawień formatowania z jednym wycinkiem:

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

Fragmentowanie ustawień formatowania

Typ wycinka ustawień formatowania składa się z dwóch typów wycinków — prostych i złożonych.

Każdy fragment zawiera właściwości formatowania. Istnieje długa lista dostępnych typów właściwości formatowania.

Przykład deklarowania wycinka ustawień formatowania typu NumUpDown z ograniczeniami:

Nazwa wycinka powinna być zgodna z nazwą właściwości z pliku 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,
            },
        }
    });

Kompilowanie modelu okienka formatowania przy użyciu narzędzi FormattingModel

settings.ts Otwórz plik.
Utwórz własny model ustawień formatowania ze wszystkimi składnikami (kartami, grupami, wycinkami, właściwościami ...) i nadaj mu VisualFormattingSettingsnazwę . Zastąp kod ustawień następującym kodem:

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

W pliku capabilities dodaj obiekty i właściwości formatowania

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

W klasie wizualizacji zaimportuj następujące elementy:

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

Deklarowanie ustawień formatowania i usługi ustawień formatowania

   private formattingSettings: VisualFormattingSettingsModel;
   private formattingSettingsService: FormattingSettingsService;

Inicjowanie usługi ustawień formatowania w konstruktorze

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

    // ...
}

Tworzenie ustawień formatowania w interfejsie API aktualizacji przy użyciu usługi ustawień formatowania populateFormattingSettingsModel

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

Kompilowanie modelu formatowania i zwracanie go w interfejsie getFormattingModel API

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

Selektor właściwości formatowania

Opcjonalny selektor we deskryptorze właściwości formatowania określa, gdzie każda właściwość jest powiązana w widoku dataView. Istnieją cztery różne opcje.

Selektor można dodać do właściwości formatowania w obiekcie deskryptora. Ten przykład jest pobierany z elementu SampleBarChart dla niestandardowych punktów danych wizualizacji przy użyciu selektorów właściwości:

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
}

Resetuj ustawienia domyślnie

Narzędzia modelu formatowania umożliwiają automatyczne resetowanie ustawień domyślnie przez automatyczne dodawanie wszystkich deskryptorów właściwości formatowania do listy funkcji formatowania, aby zastąpić domyślne deskryptory revertToDefaultDescriptors.

Możesz włączyć resetowanie ustawień formatowania z:

Przycisk domyślnego resetowania karty formatowania
Górny pasek formatowania resetuje wszystkie ustawienia do przycisku domyślnego

Lokalizacja

Aby uzyskać więcej informacji na temat funkcji lokalizacji i konfigurowania środowiska lokalizacji, zobacz Dodawanie języka lokalnego do wizualizacji usługi Power BI.

Usługa ustawień formatowania inicjowania z menedżerem lokalizacji w przypadku, gdy lokalizacja jest wymagana w wizualizacji niestandardowej:

constructor(options: VisualConstructorOptions) {

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

Dodaj displayNameKey lub descriptionKey zamiast displayName i description w odpowiednim składniku formatowania za każdym razem, gdy chcesz, aby ciąg był zlokalizowany. Przykład tworzenia wycinka formatowania z zlokalizowaną nazwą wyświetlaną i opisem

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

displayNameKey wartości i descriptionKey należy dodać do resources.json plików.

Udostępnij za pośrednictwem