Prispôsobenie tably formátu vo vlastných vizuáloch služby Power BI
Od rozhrania API verzie 5.1 môžu vývojári vytvárať vizuály, ktoré používajú novú tablu formátu Power. Vývojári môžu definovať karty a ich kategórie pre akúkoľvek vlastnosť vo vlastnom vizuáli, čo tvorcom zostáv uľahčí používanie týchto vizuálov.
Nové rozhranie API používa metódu FormattingModel na prispôsobenie častí tabiel formátu a analýzy.
Prepitné
Metóda getFormattingModel
nahrádza metódu enumerateObjectInstances
v starších verziách rozhrania API.
Vráti getFormattingModel
hodnotu FormattingModel
, ktorá definuje, ako bude vyzerať tabla formátovania a analýzy vizuálu.
Okrem všetkých starých funkcií tably formátovania podporuje nový model formátovania nové možnosti tably formátu, nové vlastnosti a nové hierarchie.
Ak chcete inovovať na rozhranie API verzie 5.1+ , nastavte apiVersion
súbor v súbore pbiviz.json na 5.1
alebo novšiu a vykonajte niektorý z týchto krokov:
- Použite pomôcku formattingmodel. (Odporúča sa)
- Bez tejto pomôcky používajte iba rozhrania API podľa nasledujúcej metódy.
Vytvorenie vizuálu podporujúceho novú tablu formátu
Vytvorenie vlastného vizuálu, ktorý používa novú tablu formátu:
Definujte všetky prispôsobiteľné
objects
v súbore capabilities.json .
Pre každý objekt sa vyžadujú nasledujúce vlastnosti:- názov objektu
- názov vlastnosti
- typ vlastnosti
Všetky ostatné vlastnosti vrátane
DisplayName
adescription
sú teraz voliteľné.Vytvorte model formátovania vlastného vizuálu. Definujte vlastnosti svojho modelu formátovania vlastného vizuálu a vytvorte ho pomocou kódu (nie JSON).
Implementujte rozhranie
getFormattingModel
API v triede vlastného vizuálu, ktorá vráti model formátovania vlastného vizuálu. (Toto rozhranie API nahrádzaenumerateObjectInstances
rozhranie , ktoré bolo použité v predchádzajúcich verziách).
Vlastnosti formátovania mapy
Ak máte vlastný vizuál vytvorený so starším rozhraním API a chcete migrovať na novú tablu formátu, alebo ak vytvárate nový vlastný vizuál:
Nastavte hodnotu v súbore
apiVersion
pbiviz.json na alebo novšiu5.1
verziu.Pre každý názov objektu a názov vlastnosti v súbore capabilities.json vytvorte zodpovedajúcu vlastnosť formátovania. Vlastnosť formátovania by mala mať popisovač, ktorý obsahuje a
propertyName
ktorý zodpovedá názvuobjectName
objektu a názvu vlastnosti v súbore capabilities.json.
Vlastnosti objects
v súbore možností majú stále rovnaký formát a nie je potrebné ich meniť.
Ak je napríklad objekt v súbore circle
capabilities.json definovaný takto:
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
Vlastnosť formátovania v modeli by mala byť typu ColorPicker
a mala by vyzerať takto:
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
Ak je pravda niektorá z nasledujúcich podmienok, zobrazí sa chyba:
- Názov objektu alebo vlastnosti v súbore možností sa nezhoduje s názvom v modeli formátovania
- Typ vlastnosti v súbore možností sa nezhoduje s typom v modeli formátovania
Model formátovania
Model formátovania je miesto, kde môžete opísať a prispôsobiť všetky vlastnosti tably formátu.
Súčasti modelu formátovania
V novom modeli formátovania sú komponenty vlastností zoskupené v logických kategóriách a podkategóriách. Tieto skupiny uľahčujú skenovanie modelu. Existuje päť základných komponentov, od najväčších po najmenšie:
Model formátovania
Najväčší kontajner tably, ktorý sa používa na formátovanie frontového rozhrania tably. Obsahuje zoznam kariet formátovania.Karta Formátovanie
Kontajner na zoskupenie vlastností najvyššej úrovne na formátovanie vlastností. Každá karta pozostáva z jednej alebo viacerých skupín formátovania, ako je to znázornené tu.Skupina formátovania
Kontajner na zoskupenie vlastností druhej úrovne. Skupina formátovania sa zobrazí ako kontajner na zoskupenie na formátovanie rýchlych filtrov.Formátovací výsek
Kontajner vlastností. Existujú dva typy rýchlych filtrov:- Jednoduchý výsek: Kontajner s jednotlivými vlastnosťami
- Zložený rýchly filter: Viacero súvisiacich kontajnerov vlastností zoskupených do jedného rýchleho filtra formátovania
Nasledujúci obrázok zobrazuje rôzne typy rýchlych filtrov. Font (Písmo) je zložený rýchly filter pozostávajúci z radu písem, veľkosti a tučného písma, kurzívy a prepínačov podčiarknutia. "Farba", "zobraziť jednotky" a ostatné výseky sú jednoduché výseky s jednou zložkou.
Vlastnosti formátovania tably vizualizácií
Každá vlastnosť v modeli formátovania by sa mala zhodovať s typom objektu v súbore capabilities.json .
Nasledujúca tabuľka zobrazuje typy vlastností formátovania v súbore capabilities.json a ich zodpovedajúcu triedu typu v moderných vlastnostiach modelu formátovania:
Typ | Typ hodnoty možností | Vlastnosť Formátovanie |
---|---|---|
Boolean | Bool | PrepínačPrepínač |
Číslo | ||
Zoznam enumerácií | enumerácia:[] | |
Farba | Výplň | Colorpicker |
Gradient | FillRule | GradientBar: hodnota vlastnosti by mala byť reťazec pozostávajúci z týchto reťazcov: minValue[,midValue],maxValue |
Text | Text |
Možnosti formátovania objektov
Typ | Typ hodnoty možností | Vlastnosť Formátovanie |
---|---|---|
Veľkosť písma | Veľkosť písma | NumUpDown |
Skupina písem | FontFamily | FontPicker |
Zarovnanie čiar | Zarovnanie | Skupina zarovnania |
Zobrazované jednotky označenia | LabelDisplayUnits (OznačeniaDisplayUnits) | Automatické rozbaľovacie okno |
* Vlastnosť formátovania zoznamu enumerácií sa líši v modeli formátovania a v súbore možností.
Deklarovať nasledujúce vlastnosti v triede nastavení formátovania vrátane zoznamu položiek enumerácie:
- ItemDropdown (Položka)
- ItemFlagsSelection
Deklarovať nasledujúce vlastnosti v triede nastavení formátovania bez zoznamu položiek enumerácie. Deklarovať zoznam položiek enumerácie v súbore capabilities.json pod príslušným objektom . (Tieto typy sú rovnaké ako v predchádzajúcich verziách rozhrania API):
- Automatické rozbaľovacie okno
- Automatické označenie výberu
Vlastnosti zloženého rýchleho filtra
Formátovací zložený výsek je výsek formátovania, ktorý obsahuje všetky naraz viacero súvisiacich vlastností.
Zatiaľ máme dva zložené typy rýchlych filtrov:
FontControl
Týmto uchovávate všetky vlastnosti súvisiace s písmom pokope. Pozostáva z nasledujúcich vlastností:- Skupina písem
- Veľkosť písma
- Tučné písmo [voliteľné]
- Kurzíva [voliteľné]
- Podčiarknutie [voliteľné]
Každá z týchto vlastností by mala mať v súbore možností zodpovedajúci objekt:
Vlastnosť Typ možností Typ formátovania Skupina písem Formátovanie: { fontFamily} FontPicker Veľkosť písma Formátovanie: {fontSize} NumUpDown Tučné Bool PrepínačPrepínač Italic Bool PrepínačPrepínač Podčiarknutie Bool PrepínačPrepínač Odsadenie okrajov určuje zarovnanie textu vo vizuáli. Pozostáva z nasledujúcich vlastností:
- Left
- Right
- Top
- Dole
Každá z týchto vlastností by mala mať v súbore možností zodpovedajúci objekt:
Vlastnosť Typ možností Typ formátovania Left Numerické NumUpDown Right Numerické NumUpDown Top Numerické NumUpDown Dole Numerické NumUpDown
Príklad: Formátovanie karty údajov
V tomto príklade si ukážeme, ako pomocou jednej karty vytvoriť model formátovania vlastného vizuálu.
Karta má dve skupiny:
- Skupina ovládacích prvkov písma s jednou zloženou vlastnosťou
- Ovládací prvok Písma
- Skupina návrhu údajov s dvomi jednoduchými vlastnosťami
- Farba písma
- Zarovnanie čiar
Najskôr pridajte objekty do súboru možností:
"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
}
}
}
}
}
}
Potom vytvorte 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;
}
Toto je výsledná tabla:
Obnovenie predvolených nastavení
Nová tabla formátu obsahuje možnosť obnoviť predvolené hodnoty všetkých vlastností karty formátovania kliknutím na tlačidlo Obnoviť predvolené, ktoré sa zobrazí na otvorenej karte.
Ak chcete túto funkciu povoliť, pridajte zoznam vlastností karty formátovania popisovačov na formátovanie karty revertToDefaultDescriptors
.
V nasledujúcom príklade je uvedené, ako pridať tlačidlo Obnoviť predvolené :
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
]
};
Pridaním revertToDefaultDescriptors
kariet formátovania tiež umožňuje obnoviť všetky vlastnosti kariet formátovania naraz kliknutím na tlačidlo Obnoviť predvolené všetky nastavenia v hornom paneli tably formátu:
Výber vlastností formátovania
Voliteľný selektor v popisovači vlastností formátovania určuje, kam sa každá vlastnosť v zobrazení údajov dataView viaže. K dispozícii sú štyri rôzne možnosti. Prečítajte si o nich v typoch selektorov objektov.
Lokalizácia
Ďalšie informácie o funkcii lokalizácie a nastavení lokalizačného prostredia nájdete v téme Pridanie lokálneho jazyka do vizuálu Power BI Pomocou správcu lokalizácie na formátovanie súčastí, ktoré chcete lokalizovať:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Ak chcete lokalizovať pomôcky formátovania modelu formátovania lokalizácie pomôcok formátovania.
Zdroje GitHubu
Všetky rozhrania modelu formátovania nájdete v GitHube – microsoft/powerbi-visuals-api: Rozhranie API vlastných vizuálov služby Power BI v časti "formatting-model-api.d.ts"
Odporúčame používať nové pomôcky formátovania modelu v GitHube – microsoft/powerbi-visuals-utils-formattingmodel: Pomôcky pre nástroje pre formátovanie modelu vizuálov služby Power BI
Môžete nájsť príklad vlastného vizuálu SampleBarChart , ktorý používa verziu API 5.1.0 a implementuje
getFormattingModel
pomocou nových pomôcok formátovania modelu v GitHube – microsoft/PowerBI-visuals-sampleBarChart: Vlastný vizuál pruhového grafu na kurz.
Súvisiaci obsah
Máte ďalšie otázky? Spýtajte sa Komunita Power BI