Anpassen des Formatbereichs in benutzerdefinierten Power BI-Visuals
Ab API-Version 5.1 können Entwickler Visuals erstellen, die den neuen Power-Formatbereich verwenden. Entwickler können die Karten und ihre Kategorien für jede Eigenschaft in ihrem benutzerdefinierten Visual definieren, sodass Berichtsersteller diese Visuals einfacher verwenden können.
Die neue API verwendet die Methode FormattingModel, um Teile des Format- und Analysebereichs anzupassen.
Tipp
Die getFormattingModel-Methode ersetzt die Methode „enumerateObjectInstances“, die in früheren API-Versionen verwendet wurde.
getFormattingModel gibt ein FormattingModel zurück, das definiert, wie der Formatierungs- und Analysebereich des Visuals aussieht.
Zusätzlich zu allen alten Formatierungsbereichsfunktionen unterstützt das neue Formatierungsmodell neue Formatbereichsfunktionen, neue Eigenschaften und neue Hierarchien.
Um ein Upgrade auf API-Version 5.1+ durchzuführen, legen Sie apiVersion in Ihrer pbiviz.json-Datei auf 5.1 oder höher und machen Sie eine der folgenden Dinge:
- Verwenden Sie formatierungsmodell util. (Empfohlen)
- Verwenden Sie ohne diese Verwendung nur APIs gemäß der folgenden Methode.
Erstellen eines Visuals, das den neuen Formatbereich unterstützt
So erstellen Sie ein benutzerdefiniertes Visual, das den neuen Formatbereich verwendet:
Definieren Sie alle anpassbaren
objectsin Ihrer capabilities.json-Datei.
Die folgenden Eigenschaften sind für jedes Objekt erforderlich:- Objektname
- -Eigenschaftsname
- Eigenschaftstyp
Alle anderen Eigenschaften, einschließlich
DisplayNameunddescription, sind jetzt optional.Erstellen Sie das benutzerdefinierte Visual FormattingModel. Definieren Sie die Eigenschaften Ihres Formatierungsmodells, für benutzerdefinierte Visuals, und erstellen Sie es mithilfe von Code (nicht JSON).
Implementieren Sie die
getFormattingModel-API in der benutzerdefinierten Visualsklasse, die ein Formatierungsmodell für benutzerdefinierte Visuals zurückgibt. (Diese API ersetztenumerateObjectInstances, der in früheren Versionen verwendet wurde.)
Kartenformatierungseigenschaften
Wenn Sie ein benutzerdefiniertes Visual mit einer älteren API erstellt haben und zum neuen Formatbereich migrieren möchten, oder wenn Sie ein neues benutzerdefiniertes Visual erstellen:
Legen Sie die
apiVersionin Ihrer pbiviz.json-Datei auf5.1oder höher fest.Erstellen Sie für jeden Objekt- und Eigenschaftsnamen in capabilities.json eine übereinstimmende Formatierungseigenschaft. Die Formatierungseigenschaft sollte über einen Deskriptor verfügen, der einen
objectNameundpropertyNameenthält, der dem Objektnamen und dem Eigenschaftennamen in capabilities.json entspricht.
Die objects-Eigenschaften in der Funktionsdatei haben weiterhin das gleiche Format und müssen nicht geändert werden.
Wenn das circle-Objekt in Ihrer capabilities.json-Datei beispielsweise 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
}
}
}
Sie erhalten eine Fehlermeldung, wenn eine der folgenden Bedingungen zutrifft:
- Der Objekt- oder Eigenschaftsname in der Funktionsdatei stimmt nicht mit dem Namen 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 neuen Formatierungsmodell werden Eigenschaftskomponenten in logischen Kategorien und Unterkategorien gruppiert. Diese Gruppen erleichtern die Überprüfung des Modells. Es gibt 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 mit Formatierungskarten.Formatierungsarte
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 Slices angezeigt.
Formatierungsslice
Eigenschaftscontainer. Es gibt zwei Arten von Slices:- Einfacher Slice: Einzelner Eigenschaftscontainer
- Zusammengesetzter Slice: Mehrere verwandte Eigenschaftscontainer, die in einem Formatierungsslice gruppiert sind
Die folgende Abbildung zeigt die verschiedenen Typen von Slices. „Schriftart“ ist ein zusammengesetzter Slice, der aus Schriftfamilie und -größe sowie Schaltern für Fett, Kursiv und Unterstrich besteht. „Farbe“, „Anzeigeeinheiten“ und die anderen Slices sind einfache Slices mit jeweils einer Komponente.
Formatierungseigenschaften des Visualisierungsbereichs
Jede Eigenschaft im Formatierungsmodell muss mit dem Objekttyp in der capabilities.json-Datei übereinstimmen.
Die folgende Tabelle zeigt die Typen der Formatierungseigenschaften in der capabilities.json-Datei und ihre übereinstimmende Typklasse in modernen Formatierungsmodelleigenschaften:
| Typ | Funktionswerttyp | Formatting-Eigenschaft |
|---|---|---|
| Boolean | Bool | ToggleSwitch |
| number | ||
| Aufzählungsliste | Enumeration:[] | |
| Color | Füllung | ColorPicker |
| Farbverlauf | FillRule | GradientBar: Der Eigenschaftswert sollte eine Zeichenfolge sein, die aus Folgendem besteht: minValue[,midValue],maxValue |
| Text | Text |
Funktionsformatierungsobjekt
| Typ | Funktionswerttyp | Formatting-Eigenschaft |
|---|---|---|
| Schriftgrad | FontSize | NumUpDown |
| Schriftfamilie | FontFamily | FontPicker |
| Linienausrichtung | Ausrichtung | AlignmentGroup |
| Bezeichnungsanzeigeeinheiten | LabelDisplayUnits | AutoDropDown |
* Die Enumerationslisten-Formatierungseigenschaft unterscheidet sich im Formatierungsmodell und in der Funktionsdatei.
Deklarieren Sie die folgenden Eigenschaften in der Klasse der Formatierungseinstellungen, einschließlich der Liste der Enumerationselemente:
- ItemDropdown
- ItemFlagsSelection
Deklarieren Sie die folgenden Eigenschaften in der Klasse der Formatierungseinstellungen ohne die Liste der Enumerationselemente. Deklarieren Sie ihre Liste der Enumerationselemente in capabilities.json unter dem entsprechenden Objekt. (Diese Typen sind dieselben wie in den früheren API-Versionen):
- AutoDropdown
- AutoFlagSelection
Zusammengesetzte Sliceeigenschaften
Ein zusammengesetzter Formatierungsschnitt ist ein Formatierungsslice, das mehrere verwandte Eigenschaften enthält.
Derzeit gibt es zwei zusammengesetzte Slicetypen:
FontControl
Dadurch bleiben alle schriftartbezogenen Eigenschaften zusammen. Es besteht aus den folgenden Eigenschaften:- Schriftfamilie
- Schriftgrad
- Fett [optional]
- Kursiv [optional]
- Unterstrichen [optional]
Jede dieser Eigenschaften sollte über ein entsprechendes Objekt in der Funktionsdatei verfügen:
Eigenschaft Funktionstyp Formatierungstyp Schriftfamilie Formatierung: { fontFamily} FontPicker Schriftgrad Formatierung: {fontSize} NumUpDown Fett Bool ToggleSwitch Kursiv Bool ToggleSwitch Underline Bool ToggleSwitch MarginPadding: Der Abstand zum Rand bestimmt die Ausrichtung des Texts im Visual. Es besteht aus den folgenden Eigenschaften:
- Left
- Right
- Oben
- Unten
Jede dieser Eigenschaften sollte über ein entsprechendes Objekt in der Funktionsdatei verfügen:
Eigenschaft Funktionstyp Formatierungstyp Links Numeric NumUpDown Right Numeric NumUpDown Oben Numeric NumUpDown Unten Numeric NumUpDown
Beispiel: Formatieren einer Datenkarte
In diesem Beispiel wird gezeigt, wie Sie ein Formatierungsmodell für benutzerdefinierte Visuals mit einer Karte erstellen.
Die Karte umfasst zwei Gruppen:
- Schriftsteuerungsgruppe mit einer zusammengesetzten Eigenschaft
- Schriftartsteuerelement
- Datenentwurfsgruppe mit zwei einfachen Eigenschaften
- Schriftfarbe
- Linienausrichtung
Fügen Sie zunächst Objekte zur Funktionsdatei hinzu:
"objects": {
"dataCard": {
"properties": {
"displayUnitsProperty": {
"type":
{
"formatting": {
"labelDisplayUnits": true
}
}
},
"fontSize": {
"type": {
"formatting": {
"fontSize": true
}
}
},
"fontFamily": {
"type": {
"formatting": {
"fontFamily": true
}
}
},
"fontBold": {
"type": {
"bool": true
}
},
"fontUnderline": {
"type": {
"bool": true
}
},
"fontItalic": {
"type": {
"bool": true
}
},
"fontColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"lineAlignment": {
"type": {
"formatting": {
"alignment": true
}
}
}
}
}
}
Erstellen Sie dann das getFormattingModel.
public getFormattingModel(): powerbi.visuals.FormattingModel {
// Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
let dataCard: powerbi.visuals.FormattingCard = {
description: "Data Card Description",
displayName: "Data Card",
uid: "dataCard_uid",
groups: []
}
// Building formatting group "Font Control Group"
// Notice that "descriptor" objectName and propertyName should match capabilities object and property names
let group1_dataFont: powerbi.visuals.FormattingGroup = {
displayName: "Font Control Group",
uid: "dataCard_fontControl_group_uid",
slices: [
{
uid: "dataCard_fontControl_displayUnits_uid",
displayName:"display units",
control: {
type: powerbi.visuals.FormattingComponent.Dropdown,
properties: {
descriptor: {
objectName: "dataCard",
propertyName:"displayUnitsProperty"
},
value: 0
}
}
},
// FontControl slice is composite slice, It means it contain multiple properties inside it
{
uid: "data_font_control_slice_uid",
displayName: "Font",
control: {
type: powerbi.visuals.FormattingComponent.FontControl,
properties: {
fontFamily: {
descriptor: {
objectName: "dataCard",
propertyName: "fontFamily"
},
value: "wf_standard-font, helvetica, arial, sans-serif"
},
fontSize: {
descriptor: {
objectName: "dataCard",
propertyName: "fontSize"
},
value: 16
},
bold: {
descriptor: {
objectName: "dataCard",
propertyName: "fontBold"
},
value: false
},
italic: {
descriptor: {
objectName: "dataCard",
propertyName: "fontItalic"
},
value: false
},
underline: {
descriptor: {
objectName: "dataCard",
propertyName: "fontUnderline"
},
value: false
}
}
}
}
],
};
// Building formatting group "Font Control Group"
// Notice that "descriptor" objectName and propertyName should match capabilities object and property names
let group2_dataDesign: powerbi.visuals.FormattingGroup = {
displayName: "Data Design Group",
uid: "dataCard_dataDesign_group_uid",
slices: [
// Adding ColorPicker simple slice for font color
{
displayName: "Font Color",
uid: "dataCard_dataDesign_fontColor_slice",
control: {
type: powerbi.visuals.FormattingComponent.ColorPicker,
properties: {
descriptor:
{
objectName: "dataCard",
propertyName: "fontColor"
},
value: { value: "#01B8AA" }
}
}
},
// Adding AlignmentGroup simple slice for line alignment
{
displayName: "Line Alignment",
uid: "dataCard_dataDesign_lineAlignment_slice",
control: {
type: powerbi.visuals.FormattingComponent.AlignmentGroup,
properties: {
descriptor:
{
objectName: "dataCard",
propertyName: "lineAlignment"
},
mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
value: "right"
}
}
},
]
};
// Add formatting groups to data card
dataCard.groups.push(group1_dataFont);
dataCard.groups.push(group2_dataDesign);
// Build and return formatting model with data card
const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
return formattingModel;
}
Hier sehen Sie den resultierenden Bereich:
Zurücksetzen auf die Standardeinstellungen
Im neuen Formatbereich können Sie alle Werte der Formatierungskarteneigenschaften auf den Standardwert zurücksetzen, indem Sie auf die Schaltfläche Auf Standard zurücksetzen klicken, die in der geöffneten Karte angezeigt wird.
Um dieses Feature zu aktivieren, fügen Sie eine Liste der Deskriptoren für Formatierungskarteneigenschaften zur Formatierungskarte „revertToDefaultDescriptors“ hinzu.
Im folgenden Beispiel wird gezeigt, wie sie die Schaltfläche Auf Standard zurücksetzen hinzufügen:
let dataCard: powerbi.visuals.FormattingCard = {
displayName: "Data Card",
// ... card parameters and groups list
revertToDefaultDescriptors: [
{
objectName: "dataCard",
propertyName:"displayUnitsProperty"
},
{
objectName: "dataCard",
propertyName: "fontFamily"
},
// ... the rest of properties descriptors
]
};
Wenn Sie revertToDefaultDescriptors zu Formatierungskarten hinzufügen, können Sie auch alle Formatierungskarteneigenschaften gleichzeitig zurückzusetzen, indem Sie in der oberen Leiste des Formatbereichs auf die Schaltfläche Alle Einstellungen auf Standard zurücksetzen klicken:
Formatieren von Eigenschaftenauswahl
Die optionale Auswahl im Deskriptor für Formatierungseigenschaften bestimmt, wo die einzelnen Eigenschaften in der dataView gebunden sind. Es gibt vier verschiedene Optionen. Erfahren Sie mehr darüber in Objektauswahltypen.
Lokalisierung
Weitere Informationen zum Lokalisierungsfeature und zum Einrichten einer Lokalisierungsumgebung finden Sie unter Hinzufügen der lokalen Sprache zu Ihrem Power BI-Visual. Verwenden Sie den Lokalisierungs-Manager zum Formatieren von Komponenten, die Sie lokalisieren möchten:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Informationen zum Lokalisieren von Hilfsprogrammen für das Formatierungsmodell finden Sie unter Formatieren von Hilfsprogrammen – Lokalisierung.
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“.
Es wird empfohlen, die neuen Formatierungsmodell-Hilfsprogramme auf GitHub: microsoft/powerbi-visuals-utils-formatierungmodel: Power BI-Visuals Formatierungsmodell-Hilfsprogramme zu verwenden.
Ein Beispiel für ein benutzerdefiniertes Visual SampleBarChart, das API-Version 5.1.0 verwendet und
getFormattingModelmit dem neuen Formatierungsmodell-Hilfsprogramm implementiert, finden Sie unter GitHub: microsoft/PowerBI-visuals-sampleBarChart: Benutzerdefiniertes Balkendiagramm-Visual für Tutorials.
Nächste Schritte
Weitere Fragen? Fragen an die Power BI-Community
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Einreichen und Feedback anzeigen für