Anpassa formatfönstret i anpassade visuella Power BI-objekt
Från och med API version 5.1 kan utvecklare skapa visuella objekt som använder det nya power-formatfönstret. Utvecklare kan definiera korten och deras kategorier för alla egenskaper i sina anpassade visuella objekt, vilket gör det enklare för rapportskapare att använda dessa visuella objekt.
Det nya API:et använder metoden FormattingModel för att anpassa delar av format- och analysrutorna.
Dricks
Metoden getFormattingModel ersätter enumerateObjectInstances metoden i tidigare API-versioner.
getFormattingModel Returnerar ett FormattingModel som definierar hur det visuella objektets formaterings- och analysfönster ser ut.
Förutom alla funktioner i det gamla formateringsfönstret har den nya formateringsmodellen stöd för nya formatfönsterfunktioner, nya egenskaper och nya hierarkier.
Om du vill uppgradera till API version 5.1+ anger du apiVersion filen i pbiviz.jsontill 5.1 eller senare och gör något av följande:
- Använd formateringsmodellverktyg. (Rekommenderas)
- Använd endast API:er enligt följande metod utan detta verktyg.
Skapa ett visuellt objekt som stöder det nya formatfönstret
Så här skapar du ett anpassat visuellt objekt som använder det nya formatfönstret:
Definiera alla anpassningsbara
objectsi filen capabilities.json .
Följande egenskaper krävs för varje objekt:- objektnamn
- egenskapsnamn
- egenskapstyp
Alla andra egenskaper, inklusive
DisplayNameochdescription, är nu valfria.Skapa den anpassade visuella formateringenModel. Definiera egenskaperna för din anpassade visuella formateringsmodell och skapa den med hjälp av kod (inte JSON).
Implementera API:et
getFormattingModeli den anpassade visuella klassen som returnerar modellen för anpassad visuell formatering. (Det här API:etenumerateObjectInstancesersätter det som användes i tidigare versioner).
Egenskaper för mappningsformatering
Om du har skapat ett anpassat visuellt objekt med ett äldre API och vill migrera till det nya formatfönstret, eller om du skapar ett nytt anpassat visuellt objekt:
apiVersionAnge i filen pbiviz.json till5.1eller senare.Skapa en matchande formateringsegenskap för varje objektnamn och egenskapsnamn i capabilities.json. Formateringsegenskapen ska ha en beskrivning som innehåller en
objectNameochpropertyNamesom matchar objektnamnet och egenskapsnamnet i capabilities.json.
Egenskaperna objects i funktionsfilen har fortfarande samma format och behöver inte ändras.
Om objektet circle i filen capabilities.json till exempel har definierats så här:
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
Formateringsegenskapen i din modell bör vara av typen ColorPicker och se ut så här:
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
Du får ett felmeddelande om något av följande villkor är sant:
- Objektet eller egenskapsnamnet i funktionsfilen matchar inte det i formateringsmodellen
- Egenskapstypen i funktionsfilen matchar inte typen i formateringsmodellen
Formateringsmodell
Formateringsmodellen är där du beskriver och anpassar alla egenskaper för formatfönstret.
Formateringsmodellkomponenter
I den nya formateringsmodellen grupperas egenskapskomponenterna i logiska kategorier och underkategorier. Dessa grupper gör modellen enklare att skanna. Det finns fem grundläggande komponenter, från största till minsta:
Formateringsmodell
Den största containern i fönstret, som används för att formatera fönstrets frontalgränssnitt. Den innehåller en lista över formateringskort.Formateringskort
Egenskaper på den översta nivån som grupperar containern för formateringsegenskaper. Varje kort består av en eller flera formateringsgrupper, som du ser här.
Formateringsgrupp
Den sekundära egenskapsgrupperingscontainern. Formateringsgruppen visas som en grupperingscontainer för formateringssektorer.
Formateringssektor
Egenskapscontainer. Det finns två typer av sektorer:- Enkelt segment: Enskild egenskapscontainer
- Sammansatt sektor: Flera relaterade egenskapscontainrar grupperade i en formateringssektor
Följande bild visar de olika typerna av sektorer. "Font" är en sammansatt sektor som består av teckensnittsfamilj, storlek och fet stil, kursiv stil och understrykningsväxlar. "Color", "display units" och de andra segmenten är enkla sektorer med en komponent vardera.
Formateringsegenskaper för visualiseringsfönster
Varje egenskap i formateringsmodellen ska matcha och objekttypen i filen capabilities.json .
I följande tabell visas formateringsegenskapstyperna i filen capabilities.json och deras matchande typklass i egenskaper för modern formateringsmodell:
| Typ | Värdetyp för funktioner | Formateringsegenskap |
|---|---|---|
| Booleskt | Bool | VäxlaSwitch |
| Antal | ||
| Uppräkningslista | uppräkning:[] | |
| Color | Fyllning | Colorpicker |
| Lutning | FillRule | GradientBar: egenskapsvärdet ska vara en sträng som består av: minValue[,midValue],maxValue |
| Text | Text |
Formateringsobjekt för funktioner
| Typ | Värdetyp för funktioner | Formateringsegenskap |
|---|---|---|
| Teckenstorlek | Teckenstorlek | NumUpDown |
| Teckensnittsfamilj | FontFamily | FontPicker |
| Linjejustering | Justering | AlignmentGroup |
| Visningsenheter för etikett | LabelDisplayUnits | AutoDropDown |
* Formateringsegenskapen för uppräkningslistan skiljer sig åt i formateringsmodellen och i funktionsfilen.
Deklarera följande egenskaper i klassen formateringsinställningar, inklusive listan över uppräkningsobjekt:
- ItemDropdown
- ItemFlagsSelection
Deklarera följande egenskaper i klassen formateringsinställningar, utan listan över uppräkningsobjekt. Deklarera listan över uppräkningsobjekt i capabilities.json under lämpligt objekt. (Dessa typer är samma som i tidigare API-versioner):
- AutoDropdown
- AutoFlagSelection
Egenskaper för sammansatt sektor
En formatering av sammansatt sektor är en formateringssektor som innehåller flera relaterade egenskaper tillsammans.
För tillfället har vi två sammansatta segmenttyper:
FontControl
Detta håller ihop alla teckensnittsrelaterade egenskaper. Den består av följande egenskaper:- Teckensnittsfamilj
- Teckenstorlek
- Fetstil [valfritt]
- Kursiv [valfritt]
- Understrykning [valfritt]
Var och en av dessa egenskaper bör ha ett motsvarande objekt i funktionsfilen:
Property Typ av funktioner Formateringstyp Teckensnittsfamilj Formatering: { fontFamily} FontPicker Teckenstorlek Formatering: {fontSize} NumUpDown Fetstil Bool VäxlaSwitch Italic Bool VäxlaSwitch Understruken Bool VäxlaSwitch MarginPadding Margin-utfyllnad avgör justeringen av texten i det visuella objektet. Den består av följande egenskaper:
- Vänster
- Right
- Främsta
- Nederkant
Var och en av dessa egenskaper bör ha ett motsvarande objekt i funktionsfilen:
Property Typ av funktioner Formateringstyp Vänster Numerisk NumUpDown Right Numerisk NumUpDown Främsta Numerisk NumUpDown Nederkant Numerisk NumUpDown
Exempel: Formatera ett datakort
I det här exemplet visar vi hur du skapar en anpassad modell för visuell formatering med ett kort.
Kortet har två grupper:
- Teckensnittskontrollgrupp med en sammansatt egenskap
- Teckensnittskontroll
- Datadesigngrupp med två enkla egenskaper
- Teckenfärg
- Linjejustering
Lägg först till objekt i funktionsfilen:
"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
}
}
}
}
}
}
Skapa sedan 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;
}
Här är det resulterande fönstret:
Återställ inställningarna till standard
Det nya formatfönstret har möjlighet att återställa alla värden för formateringskortegenskaper till standard genom att klicka på knappen Återställ till standard som visas på det öppna kortet.
Om du vill aktivera den här funktionen lägger du till en lista med formateringskortegenskaper som beskriver formateringskortet revertToDefaultDescriptors.
I följande exempel visas hur du lägger till återställningen till standardknappen :
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
]
};
Genom att lägga revertToDefaultDescriptors till formateringskort kan du också återställa alla formateringskortsegenskaper samtidigt genom att klicka på knappen Återställ alla inställningar till standard i det övre fältet i formatfönstret:
Formatera egenskapsväljare
Den valfria väljaren i formateringsegenskaper bestämmer var varje egenskap är bunden i dataView. Det finns fyra olika alternativ. Läs om dem i objektväljare.
Lokalisering
Mer information om lokaliseringsfunktionen och hur du konfigurerar en lokaliseringsmiljö finns i Lägga till det lokala språket i ditt visuella Power BI-objekt Använd lokaliseringshanteraren för att formatera komponenter som du vill lokalisera:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Om du vill lokalisera formateringsmodellen används formateringsanspråk för lokalisering.
GitHub-resurser
Alla formateringsmodellgränssnitt finns i GitHub – microsoft/powerbi-visuals-api: Api för anpassade visuella Power BI-objekt i "formateringsmodell-api.d.ts"
Vi rekommenderar att du använder de nya formateringsmodellverktygen på GitHub – microsoft/powerbi-visuals-utils-formattingmodel: Power BI visuals formatting model helper utils
Du hittar ett exempel på ett anpassat visuellt SampleBarChart som använder API version 5.1.0 och implementerar
getFormattingModelmed hjälp av de nya formateringsmodellverktygen på GitHub – microsoft/PowerBI-visuals-sampleBarChart: Bar Chart Custom Visual for tutorial.
Relaterat innehåll
Har du fler frågor? Fråga Power BI Community
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för