Auf Englisch lesen

Freigeben über

FormattingModel-Utils

  • Artikel

FormattingModel-Utils enthält die Klassen, Schnittstellen und Methoden, die zum Erstellen eines Formatierungseinstellungsmodells erforderlich sind, um die Eigenschaftenbereiche (Format- und Analysebereiche) Ihres benutzerdefinierten visuellen Power BI-Elements auszufüllen.

Formatierungseinstellungsdienst

Der Formatierungseinstellungsdienst empfängt ein Formatierungseinstellungsmodell und wandelt es in ein Formatierungsmodell um, das den Formatierungsbereich ausfüllt. Der Formatierungsmodelldienst unterstützt auch Zeichenfolgenlokalisierungen.

Initialisieren des Formatierungseinstellungsdiensts:

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

Die Schnittstelle für den Formatierungseinstellungsdienst IFormattingSettingsService verfügt über zwei Standardmethoden:

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

Formatierungseinstellungsmodell

Das Einstellungsmodell enthält und umschließt alle Formatierungskarten für den Formatierungsbereich und den Analysebereich.

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

In diesem Beispiel wird ein neues Formatierungseinstellungsmodell deklariert:

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

Karte mit Formatierungseinstellungen

Eine Karte mit Formatierungseinstellungen legt eine Formatierungskarte im Formatierungs- oder Analysebereich fest. Eine Karte mit Formatierungseinstellungen kann mehrere Formatierungsslices, Container, Gruppen und Eigenschaften enthalten.

Durch das Hinzufügen von Slices zu einer Karte mit Formatierungseinstellungen werden alle diese Segmente in einer Formatierungskarte zusammengefasst.

Karten, Segmente und Gruppen können dynamisch ausgeblendet werden, indem sie den visible Parameter auf false festlegen (standardmäßig true).

Der Karte kann entweder den Formatierungsbereich oder den Analysebereich ausfüllen, indem der Parameter analyticsPane auf true bzw. false festgelegt wird.

Beispiel zum Deklarieren der Karte für Formatierungseinstellungen, einschließlich einer Formatierungseinstellungsgruppe und eines Datenschnitts:

  • Der Kartenname sollte dem Objektnamen in capabilities.json entsprechen.
  • Der Slicename sollte mit dem Eigenschaftennamen in capabilities.json übereinstimmen.
TypeScript 
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];
}

Die Eigenschaftsdeklaration in capabilities.json sollte wie folgt lauten:

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

Formatierungseinstellungsgruppe

Einige Formatierungseinstellungen Karte können Gruppen enthalten. Gruppen bestehen aus Segmenten und können erweitert/reduziert werden.

Beispiel zum Deklarieren der Formatierungseinstellungengruppe mit einem Segment:

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

Slice mit Formatierungseinstellungen

Der Slicetyp für Formatierungseinstellungen besteht aus zwei Typen von Slices: einfach und zusammengesetzt.

Jeder Slice enthält Formatierungseigenschaften. Es gibt eine lange Liste verfügbarer Formatierungseigenschaftentypen.

Beispiel zum Deklarieren von Formatierungseinstellungen des Typs NumUpDown mit Einschränkungen:

Der Slicename sollte dem Eigenschaftennamen in capabilities.json entsprechen.

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

Erstellen eines Formatierungsbereichsmodells mithilfe von FormattingModel-Utils

  1. Öffnen Sie erneut Ihre Datei settings.ts.
  2. Erstellen Sie ein eigenes Formatierungseinstellungsmodell mit allen zugehörigen Komponenten (Karten, Gruppen, Slices, Eigenschaften ...), und nennen Sie es VisualFormattingSettings. Ersetzen Sie den Einstellungscode durch folgenden Code:
TypeScript 
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];
}
  1. Fügen Sie in der Datei „capabilities.json“ Ihre Formatierungsobjekte und Eigenschaften hinzu.
JSON 
"objects": {
    "myVisualCard": {
        "properties": {
            "myNumericSlice": {
                "type": {
                    "numeric": true 
                }
            }
        }
    }
}
  1. Importieren Sie In Ihrer Klasse für das visuelle Element Folgendes:
TypeScript 
import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";
import { VisualFormattingSettingsModel } from "./settings";
  1. Deklarieren von Formatierungseinstellungen und Formatierungseinstellungsdienst
TypeScript 
   private formattingSettings: VisualFormattingSettingsModel;
   private formattingSettingsService: FormattingSettingsService;
  1. Initialisieren des Formatierungseinstellungsdiensts im Konstruktor
TypeScript 
constructor(options: VisualConstructorOptions) {
    this.formattingSettingsService = new FormattingSettingsService();

    // ...
}
  1. Erstellen von Formatierungseinstellungen in der Update-API mithilfe des Formatierungseinstellungsdiensts populateFormattingSettingsModel
TypeScript 
public update(options: VisualUpdateOptions) {
    this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews);
    // ...
}
  1. Erstellen eines Formatierungsmodells und Zurückgeben dieses Modells in der getFormattingModel-API
TypeScript 
public getFormattingModel(): powerbi.visuals.FormattingModel {
    return this.formattingSettingsService.buildFormattingModel(this.formattingSettings);
}

Formatieren von Eigenschaftenauswahl

Die optionale Auswahl im Deskriptor für Formatierungseigenschaften bestimmt, wo die einzelnen Eigenschaften in der dataView gebunden werden. Es gibt vier verschiedene Optionen.

Sie können der Formatierungseigenschaft in ihrem Deskriptorobjekt einen Selektor hinzufügen. Dieses Beispiel stammt aus SampleBarChart für das Einfärben benutzerdefinierter visueller Datenpunkte mithilfe von Eigenschaftenselektoren:

TypeScript 
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
}

Zurücksetzen auf die Standardeinstellungen

Mithilfe von Formatierungsmodell-Hilfsprogrammen können Sie Einstellungen auf den Standardwert zurücksetzen, indem Sie automatisch alle Formatierungseigenschaftendeskriptoren der Liste der Features auf der Formatierungskarte hinzufügen, die auf Standarddeskriptoren revertToDefaultDescriptors zurückgesetzt werden sollen.

Sie können das Zurücksetzen von Formatierungseinstellungen hier aktivieren:

  • Schaltfläche Auf Standard zurücksetzen auf der Formatierungskarte

    Screenshot: Schaltfläche „Auf Standard zurücksetzen“ der Formatkarte

  • Schaltfläche Alle Einstellungen auf Standardwerte zurücksetzen in der oberen Leiste des Formatierungsbereichs

    Screenshot: Schaltfläche „Alle Einstellungen auf Standardwerte zurücksetzen“ im Formatbereich

Lokalisierung

Weitere Informationen zum Lokalisierungsfeature und zum Einrichten der Lokalisierungsumgebung finden Sie unter Hinzufügen der lokalen Sprache zu Ihrem visuellen Power BI-Element.

Initialisieren Sie den Formatierungseinstellungsdienst mit dem Lokalisierungsmanager, falls eine Lokalisierung in Ihrem benutzerdefinierten visuellen Element erforderlich ist:

TypeScript 
constructor(options: VisualConstructorOptions) {

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

Fügen Sie displayNameKey oder descriptionKey anstelle von displayName und description in der entsprechenden Formatierungskomponente hinzu, wenn eine Zeichenfolge lokalisiert werden soll. Beispiel für das Erstellen eines Formatierungsslices mit lokalisiertem Anzeigenamen und einer lokalisierten Beschreibung

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

Die Werte für displayNameKey und descriptionKey sollten den resources.json-Dateien hinzugefügt werden.