Der Formatbereich in benutzerdefinierten Power BI-Visuals

Mithilfe von API Version 5.1 und höher können Entwickler visuelle Elemente mit dem Bereich "Format" erstellen. Entwickler können die Karten und deren Kategorien für jede Eigenschaft in ihrer benutzerdefinierten visuellen Darstellung definieren, sodass Berichtsersteller diese visuellen Elemente einfacher verwenden können.

Die API verwendet die FormattingModel-Methode , um Teile des Formats und der Analysebereiche anzupassen.

getFormattingModel gibt ein FormattingModel zurück, das definiert, wie der Formatierungs- und Analysebereich des visuellen Elements aussieht.

Zusätzlich zu allen alten Formatierungsbereichsfunktionen unterstützt das Formatierungsmodell aktuelle Formatbereichsfunktionen, Eigenschaften und Hierarchien.

Erstellen eines visuellen Elements, das den neuesten Bereich "Format" unterstützt

Allgemeine Schritte zum Hinzufügen der Formatbereichsunterstützung zu einem benutzerdefinierten Visual:

1. Legen Sie die apiVersion in Ihrer pbiviz.json-Datei auf 5.1 oder höher fest.

2. Definieren Sie alle anpassbaren objects Daten in Ihrer capabilities.json Datei. Diese Objekte werden dann den Eigenschaften des Formatierungsbereichs zugeordnet . Für jedes Objekt sind die folgenden Eigenschaften erforderlich:

   • Objektname
   • Eigenschaftsname
   • Eigenschaftstyp

   Alle anderen Eigenschaften, einschließlich DisplayName und description, sind jetzt optional.

3. Erstellen Sie das benutzerdefinierte visuelle Formatierungsmodell , indem Sie eine der folgenden Aktionen ausführen:

   • Verwenden Sie Formatierungsmodell Util. (Empfohlen)
   • Ohne dieses Tool verwenden Sie nur APIs.

Definieren Sie die Eigenschaften Ihres benutzerdefinierten visuellen Formatierungsmodells, und erstellen Sie es mit Code (nicht JSON).

4. Implementieren Sie die getFormattingModel API in der benutzerdefinierten visuellen Klasse, die ein benutzerdefiniertes visuelles Formatierungsmodell zurückgibt. (Diese API ersetzt die in früheren Versionen verwendete enumerateObjectInstances).

Beispiel für die Implementierung des Formatierungsmodells

• Formatierungsmodell mithilfe des Beispiels für formattingmodel util. (Empfohlen)
• Formatierungsmodell mit nur APIs (Beispiel).

Kartenformatierungseigenschaften

Wenn Sie ein benutzerdefiniertes visuelles Element mit einer älteren API erstellt haben und sie mit dem Formatbereich aktualisieren möchten, oder wenn Sie ein neues benutzerdefiniertes visuelles Element erstellen:

1. Legen Sie die apiVersion in Ihrer pbiviz.json-Datei auf 5.1 oder höher fest.

2. Erstellen Sie für jeden Objektnamen und Eigenschaftennamen in capabilities.json eine entsprechende Formatierungseigenschaft. Die Formatierungseigenschaft sollte über einen Deskriptor verfügen, der einen objectName enthält und propertyName dem Objektnamen und dem Eigenschaftsnamen in capabilities.jsonentspricht.

Die objects Eigenschaften in der Funktionsdatei weisen weiterhin dasselbe Format auf und müssen nicht geändert werden.

Beispiel: Wenn das circle Objekt in Ihrer capabilities.json Datei wie folgt definiert ist:

"objects": {
    "circle": {
        "properties": {
            "circleColor": {
                "type": {
                    "fill": {
                        "solid": {
                            "color": true
                        }
                    }
                }
            },
        }
    }
}

Die Formatierungseigenschaft in Ihrem Modell sollte vom Typ ColorPicker sein und wie folgt aussehen:

control: {
    type: "ColorPicker",
    properties: {
        descriptor: {
            objectName: "circle",
            propertyName: "circleColor"
        },
        value: {
            value: this.visualSettings.circle.circleColor
        }
    }
}

Wenn eine der folgenden Bedingungen erfüllt ist, wird ein Fehler angezeigt:

• Der Objekt- oder Eigenschaftenname in der Funktionsdatei stimmt nicht mit dem Objekt im Formatierungsmodell überein.
• Der Eigenschaftentyp in der Funktionsdatei stimmt nicht mit dem Typ im Formatierungsmodell überein.

Formatierungsmodell

Im Formatierungsmodell beschreiben und passen Sie alle Eigenschaften Ihres Formatbereichs an.

Komponenten des Formatierungsmodells

Im Formatierungsmodell werden Eigenschaftenkomponenten in logischen Kategorien und Unterkategorien gruppiert. Diese Gruppen erleichtern das Scannen des Modells. Es gibt die fünf grundlegenden Komponenten, von der größten bis zur kleinsten:

• Formatierungsmodell Der größte Bereichscontainer, der zum Formatieren der Frontalschnittstelle des Bereichs verwendet wird. Sie enthält eine Liste der Formatierungskarten.

• Formatierungskarte Der Container für die Gruppierung von Eigenschaften der obersten Ebene für Formatierungseigenschaften. Jede Karte besteht aus einer oder mehreren Formatierungsgruppen, wie hier gezeigt.

  

• Formatierungsgruppe
  Der Container für die Gruppierung von Eigenschaften der zweiten Ebene. Die Formatierungsgruppe wird als Gruppierungscontainer zum Formatieren von Segmenten angezeigt.

  

• Formatierungscontainer
  Der Container für die Gruppierung von Eigenschaften der zweiten Ebene. Der Formatierungscontainer gruppiert Formatierungssegmente in separate Containerelemente und ermöglicht es, mithilfe einer Dropdownliste zwischen ihnen zu wechseln.

  

• Segment formatieren
  Eigenschaftscontainer. Es gibt zwei Arten von Slices:

  • Einfacher Slice: Einzelner Eigenschaftscontainer
  • Zusammengesetztes Segment: Mehrere verknüpfte Eigenschaftencontainer in einem Formatierungssegment gruppiert

  Die folgende Abbildung zeigt die verschiedenen Typen von Slices. "Schriftart" ist ein zusammengesetzter Abschnitt, der aus Schriftfamilie, Schriftgröße sowie Schaltern für Fett, Kursiv und Unterstreichen besteht. „Farbe“, „Anzeigeeinheiten“ und die anderen Slices sind einfache Slices mit jeweils einer Komponente.

  

Formatierungseigenschaften des Visualisierungsbereichs

Jede Eigenschaft im Formatierungsmodell sollte mit dem Objekttyp in der capabilities.json Datei übereinstimmen.

Die folgende Tabelle zeigt die Formatierungstypen in Datei capabilities.json und deren übereinstimmende Typklasse in modernen Formatierungsmodelleigenschaften:

Funktionen zum Formatieren von Objekten

^* Die Enumerationslistenformatierungseigenschaft unterscheidet sich im Formatierungsmodell und in der Funktionsdatei.

• Deklarieren Sie die folgenden Eigenschaften in der Formateinstellungsklasse, einschließlich der Liste der Enumerationselemente:

  • ItemDropdown
  • ItemFlagsSelection

• Deklarieren Sie die folgenden Eigenschaften in der Formateinstellungsklasse, ohne die Liste der Enumerationselemente. Deklarieren Sie die Enumerationselementeliste in capabilities.json unter dem entsprechenden Objekt. (Diese Typen sind identisch mit den vorherigen API-Versionen):

  • AutoDropdown
  • AutomatischeFlaggenAuswahl

Zusammengesetzte Sliceeigenschaften

Ein zusammengesetztes Formatierungssegment ist ein Formatierungssegment, das mehrere verwandte Eigenschaften umfasst.

Derzeit gibt es zwei zusammengesetzte Slicetypen:

• FontControl
  Dadurch werden alle schriftartbezogenen Eigenschaften zusammengehalten. Sie besteht aus den folgenden Eigenschaften:

  • Schriftfamilie
  • Schriftgröße
  • Fett [optional]
  • Kursiv [optional]
  • Unterstrichen [optional]

  

  Jede dieser Eigenschaften sollte über ein entsprechendes Objekt in der Funktionsdatei verfügen:

  Eigentum	Typ der Fähigkeiten	Formatierungstyp
  Schriftfamilie	Formatierung: { fontFamily}	FontPicker
  Schriftgröße	Formatierung: {fontSize}	NumUpDown
  Fett	Boolesch	Umschalten
  Kursiv	Boolesch	Umschalten
  Unterstreichen	Boolesch	Umschalten

• MarginPadding Der Randabstand bestimmt die Ausrichtung des Texts im visuellen Element. Sie besteht aus den folgenden Eigenschaften:

  • Nach links
  • Richtig
  • Nach oben
  • Unterseite

  Jede dieser Eigenschaften sollte über ein entsprechendes Objekt in der Funktionsdatei verfügen:

  Eigentum	Typ der Fähigkeiten	Formatierungstyp
  Nach links	Numerisch	NumUpDown
  Richtig	Numerisch	NumUpDown
  Nach oben	Numerisch	NumUpDown
  Unterseite	Numerisch	NumUpDown

GitHub-Ressourcen

• Alle Formatierungsmodellschnittstellen finden Sie in GitHub: microsoft/powerbi-visuals-api: API für Benutzerdefinierte Power BI-Visuals unter „formatierung-model-api.d.ts“.

• Wir empfehlen die Verwendung der neuesten Hilfsprogramme für das Formatierungsmodell bei GitHub – microsoft/powerbi-visuals-utils-formattingmodel: Hilfsprogramme für das Power BI-Formatierungsmodell

• Sie finden ein Beispiel für ein benutzerdefiniertes visuelles Element SampleBarChart, das die API-Version 5.1.0 verwendet und mithilfe der neuesten Formatierungsmodell-Utils getFormattingModel implementiert wird unter GitHub – microsoft/PowerBI-visuals-sampleBarChart: Balkendiagramm als benutzerdefiniertes Visual für ein Tutorial.

Verwandte Inhalte

Weitere Fragen? Fragen an die Power BI-Community