Přizpůsobení podokna formátu ve vlastních vizuálech Power BI
Od rozhraní API verze 5.1 můžou vývojáři vytvářet vizuály, které používají nové podokno formátu Power. Vývojáři můžou definovat karty a jejich kategorie pro libovolnou vlastnost ve vlastním vizuálu, což tvůrcům sestav usnadní používání těchto vizuálů.
Nové rozhraní API používá metodu FormattingModel k přizpůsobení částí podokna formátování a analýzy.
Tip
Metoda getFormattingModel nahradí metodu enumerateObjectInstances ve starších verzích rozhraní API.
Vrátí getFormattingModel hodnotu FormattingModel , která definuje vzhled formátování a podokna analýzy vizuálu.
Kromě všech starých funkcí podokna formátování nový model formátování podporuje nové možnosti podokna formátování, nové vlastnosti a nové hierarchie.
Pokud chcete upgradovat na rozhraní API verze 5.1 nebo novější, nastavte apiVersion soubor pbiviz.json na 5.1 nebo novější a proveďte jednu z následujících věcí:
- Použijte nástroj pro formátovací model. (Doporučeno)
- Bez tohoto nástroje používejte pouze rozhraní API podle následující metody.
Vytvoření vizuálu, který podporuje nové podokno formátu
Vytvoření vlastního vizuálu, který používá nové podokno formátu:
Definujte všechny přizpůsobitelné
objectssoubory v souboru capabilities.json .
Pro každý objekt jsou vyžadovány následující vlastnosti:- název objektu
- název vlastnosti
- typ vlastnosti
Všechny ostatní vlastnosti, včetně
DisplayNameadescription, jsou nyní volitelné.Sestavte vlastní formátovací model vizuálu. Definujte vlastnosti vlastního modelu formátování vizuálu a sestavte ho pomocí kódu (ne JSON).
getFormattingModelImplementujte rozhraní API ve třídě vlastního vizuálu, které vrací model formátování vlastního vizuálu. (Toto rozhraní API nahrazujeenumerateObjectInstancespoužité v předchozích verzích.
Vlastnosti formátování mapy
Pokud máte vlastní vizuál vytvořený pomocí staršího rozhraní API a chcete migrovat do nového podokna formátu nebo pokud vytváříte nový vlastní vizuál:
apiVersionNastavte soubor pbiviz.json5.1na nebo novější.Pro každý název objektu a název vlastnosti v capabilities.json vytvořte odpovídající vlastnost formátování. Vlastnost formátování by měla mít popisovač, který obsahuje
objectNamenázev objektu a název vlastnosti v souboru capabilities.json.propertyName
Vlastnosti objects v souboru funkcí mají stále stejný formát a není nutné je měnit.
Pokud je například circle objekt v souboru capabilities.json definovaný takto:
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
Vlastnost formátování v modelu by měla být typu ColorPicker a měla by vypadat takto:
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
Pokud platí jedna z následujících podmínek, zobrazí se chyba:
- Název objektu nebo vlastnosti v souboru funkcí neodpovídá názvu objektu v modelu formátování.
- Typ vlastnosti v souboru funkcí neodpovídá typu v modelu formátování.
Formátovací model
Formátovací model je místo, kde popisujete a přizpůsobíte všechny vlastnosti podokna formátování.
Formátování součástí modelu
V novém modelu formátování jsou komponenty vlastností seskupené do logických kategorií a podkategorií. Tyto skupiny usnadňují prohledávání modelu. Existuje pět základních komponent, od největších po nejmenší:
Formátovací model
Největší kontejner podokna, který se používá k formátování frontálního rozhraní podokna. Obsahuje seznam karet formátování.Karta formátování
Kontejner vlastností nejvyšší úrovně seskupuje pro vlastnosti formátování. Každá karta se skládá z jedné nebo více skupin formátování, jak je znázorněno zde.
Skupina formátování
Kontejner seskupování vlastností na sekundární úrovni Skupina formátování se zobrazí jako kontejner seskupení pro formátování řezů.
Formátování řezu
Kontejner vlastností. Existují dva typy řezů:- Jednoduchý řez: Kontejner jednotlivých vlastností
- Složený řez: Více kontejnerů souvisejících vlastností seskupených do jednoho řezu formátování
Následující obrázek znázorňuje různé typy řezů. "Písmo" je složený řez skládající se z rodiny písem, velikosti a tučného písma, kurzívy a přepínačů podtržení. "Color", "display units" a ostatní řezy jsou jednoduché řezy s jednou komponentou.
Vlastnosti formátování podokna Vizualizace
Každá vlastnost v modelu formátování by se měla shodovat a typ objektu v souboru capabilities.json .
Následující tabulka ukazuje typy vlastností formátování v souboru capabilities.json a jejich odpovídající třídu typů ve vlastnostech moderního modelu formátování:
| Typ | Typ hodnoty schopností | Vlastnost formátování |
|---|---|---|
| Boolean | Bool | SwitchSwitch |
| Počet | ||
| Seznam výčtů | výčet:[] | |
| Barva | Výplň | ColorPicker |
| Přechod | Fillrule | GradientBar: Hodnota vlastnosti by měla být řetězec skládající se z: minValue[,midValue],maxValue |
| Text | Text |
Možnosti formátování objektů
| Typ | Typ hodnoty schopností | Vlastnost formátování |
|---|---|---|
| Velikost písma | FontSize | NumUpDown |
| Rodina písem | Fontfamily | FontPicker |
| Zarovnání čáry | Zarovnání | AlignmentGroup |
| Jednotky zobrazení popisků | PopisekDisplayUnits | AutoDropDown |
* Vlastnost formátování seznamu výčtů se liší v modelu formátování a v souboru funkcí.
Deklarujte následující vlastnosti ve třídě nastavení formátování, včetně seznamu položek výčtu:
- ItemDropdown
- ItemFlagsSelection
Deklarujte následující vlastnosti ve třídě nastavení formátování bez seznamu položek výčtu. Deklarujte seznam položek výčtu v souboru capabilities.json v příslušném objektu. (Tyto typy jsou stejné jako v předchozích verzích rozhraní API):
- AutoDropdown
- AutoFlagSelection
Vlastnosti složeného řezu
Složený řez je formátovací řez, který obsahuje více souvisejících vlastností.
Prozatím máme dva složené typy řezů:
FontControl
Tím jsou všechny vlastnosti související s písmem pohromadě. Skládá se z následujících vlastností:- Rodina písem
- Velikost písma
- Tučné [volitelné]
- Kurzíva [volitelné]
- Podtržení [volitelné]
Každá z těchto vlastností by měla mít odpovídající objekt v souboru schopností:
Vlastnost Typ schopností Typ formátování Rodina písem Formátování: { fontFamily} FontPicker Velikost písma Formátování: {fontSize} NumUpDown Tučné Bool SwitchSwitch Italic Bool SwitchSwitch Podtržené Bool SwitchSwitch Odsazení okraje MarginPadding určuje zarovnání textu ve vizuálu. Skládá se z následujících vlastností:
- Šipka vlevo
- Right
- Hlavní
- Dole
Každá z těchto vlastností by měla mít odpovídající objekt v souboru schopností:
Vlastnost Typ schopností Typ formátování Šipka vlevo Číslo NumUpDown Right Číslo NumUpDown Hlavní Číslo NumUpDown Dole Číslo NumUpDown
Příklad: Formátování datové karty
V tomto příkladu si ukážeme, jak vytvořit vlastní model formátování vizuálu s jednou kartou.
Karta má dvě skupiny:
- Skupina ovládacích prvků písem s jednou složenou vlastností
- Ovládací prvek Písmo
- Skupina návrhu dat se dvěma jednoduchými vlastnostmi
- Barva písma
- Zarovnání čáry
Nejprve přidejte objekty do souboru schopností:
"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
}
}
}
}
}
}
Pak vytvořte 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;
}
Tady je výsledné podokno:
Obnovit výchozí nastavení
Nové podokno formát má možnost obnovit výchozí hodnoty vlastností všech formátových karet kliknutím na tlačítko Obnovit výchozí, které se zobrazí na otevřené kartě.
Chcete-li tuto funkci povolit, přidejte do karty revertToDefaultDescriptorsformátování seznam vlastností formátování karet .
Následující příklad ukazuje, jak přidat výchozí tlačítko resetování :
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
]
};
Přidáním revertToDefaultDescriptors na karty formátování je také možné obnovit všechny vlastnosti karet formátování najednou kliknutím na tlačítko Obnovit všechna nastavení na výchozím tlačítku v horním panelu podokna formátování:
Selektor vlastností formátování
Volitelný selektor ve formátovací vlastnosti popisovač určuje, kde každá vlastnost je vázána v dataView. Existují čtyři různé možnosti. Přečtěte si o nich v typech selektorů objektů.
Lokalizace
Další informace o lokalizační funkci a nastavení lokalizačního prostředí najdete v tématu Přidání místního jazyka do vizuálu Power BI pomocí správce lokalizace k formátování komponent, které chcete lokalizovat:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Lokalizace lokalizací nástrojů pro formátování modelu
Prostředky GitHubu
Všechna rozhraní modelu formátování najdete na GitHubu – microsoft/powerbi-visuals-api: Rozhraní API vlastních vizuálů Power BI v souboru formatting-model-api.d.ts
Doporučujeme používat nové nástroje pro formátování modelu na GitHubu – microsoft/powerbi-visuals-utils-formattingmodel: Pomocné nástroje pro formátování modelů vizuálů Power BI
Můžete najít příklad vlastního vizuálu SampleBarChart , který používá rozhraní API verze 5.1.0 a implementuje
getFormattingModelpomocí nových nástrojů pro modelování formátování na GitHubu – microsoft/PowerBI-visuals-sampleBarChart: Vlastní vizuál pruhového grafu pro kurz.
Související obsah
Máte ještě další otázky? Zeptejte se Komunita Power BI
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro