Podokno formátování ve vizuálech na míru Power BI

Článek
12/21/2024

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átu a analýzy.

Spropitné

Metoda getFormattingModel nahrazuje metodu enumerateObjectInstances ve starších verzích rozhraní API.

getFormattingModel vrátí 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.

Snímek obrazovky s novým oknem formátování

Vytvořte vizuál podporující nové podokno formátu

Obecné kroky pro přidání podpory nového podokna formátu do vlastního vizuálu:

Nastavte apiVersion v souboru pbiviz.json na 5.1 nebo novější.
Definujte všechny přizpůsobitelné objects v souboru capabilities.json. Tyto objekty se pak mapují na vlastnosti podokna formátování. 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ě DisplayName a description, jsou teď volitelné.
Vytvořte vlastní vizuál FormattingModel provedením jednoho z následujících kroků:
- Použijte formátovací model util. (Doporučené)
- Bez tohoto nástroje používejte pouze rozhraní API.

Definujte vlastnosti vlastního modelu formátování vizuálu a sestavte ho pomocí kódu (ne JSON).

Implementujte rozhraní API getFormattingModel ve třídě vlastního vizuálu, která vrací model formátování vlastního vizuálu. (Toto rozhraní API nahrazuje enumerateObjectInstances použité ve verzích předchozích).

Příklad implementace modelu formátování

Formátování modelu pomocí formátovacího modelu utilitu příklad. (Doporučeno)
Formátování modelu pouze pomocí rozhraní API příkladu.

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:

Nastavte apiVersion v souboru pbiviz.json na 5.1 nebo novější.
Pro každý název objektu a název vlastnosti v capabilities.jsonvytvořte odpovídající vlastnost formátování. Vlastnost formátování by měla mít popisovač, který obsahuje objectName a propertyName, které odpovídají názvu objektu a názvu vlastnosti v capabilities.json.

Vlastnosti objects v souboru funkcí mají stále stejný formát a není nutné je měnit.

Pokud je například objekt circle v souboru capabilities.json definován 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 je splněna 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ší podoknový kontejner, který se používá k formátování předního rozhraní podokna. Obsahuje seznam karet formátování.
Karta Formátování Kontejner nejvyšší úrovně pro seskupení vlastností formátování. Každá karta se skládá z jedné nebo více skupin formátování, jak je znázorněno zde.
skupiny formátování
Kontejner pro seskupení vlastností na sekundární úrovni Skupina formátování se zobrazí jako seskupovací kontejner pro formátování plátků.
formátování kontejneru
Kontejner pro seskupování vlastností na sekundární úrovni Kontejner pro formátování seskupuje formátovací úseky do samostatných položek v kontejneru a umožňuje přepínání mezi nimi pomocí rozevíracího seznamu.
Formátování řezu
Úložiště vlastností. Existují dva typy řezů:
- Jednoduchý úsek: Kontejner jednotlivých atributů
- složený výřez: Několik kontejnerů souvisejících vlastností seskupených do jednoho výřezu formátování
Následující obrázek znázorňuje různé typy řezů. "Písmo" je složená jednotka skládající se z rodiny písem, velikosti a přepínačů pro tučné písmo, kurzívu a podtržení. "Barva", "jednotky zobrazení" 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í
Booleovský	Bool	přepínací tlačítko
Číslo	číselný celé číslo	NumUpDown Posuvník
Výčtový seznam	výčet:[]	ItemDropdown ItemFlagsSelection AutoDropdown AutomatickýVýběrVlajek ^* Viz poznámka níže
Barva	Vyplnit	Výběr barvy
Spád	FillRule	GradientBar: Hodnota vlastnosti by měla být řetězec skládající se z: `minValue[,midValue],maxValue`
Text	Text	Vstupní text Textové pole

Možnosti formátování objektů

Typ	Typ hodnoty schopností	Vlastnost formátování
Velikost písma	Velikost písma	NumUpDown
Rodina písem	FontFamily	Výběr Písma
Zarovnání čáry	Zarovnání	SkupinaZarovnání
Jednotky zobrazení popisků	ŠtítekJednotkyZobrazení	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:
- Rozbalovací nabídka položek
- VýběrPoložkovýchPříznaků
Deklarujte následující vlastnosti ve třídě nastavení formátování bez seznamu položek výčtu. Deklarujte jejich seznam položek výčtu v capabilities.json pod příslušným objektem. (Tyto typy jsou stejné jako v předchozích verzích rozhraní API):
- Automatické rozbalovací menu
- Automatický výběr vlajky

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 typy kompozitních ř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é]

Snímek obrazovky s složeným řezem písma s rodinou písem, velikostí písma, tučným písmem, kurzívou a možnostmi podtržení

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	Přepínač
Kurzíva	Bool	Kolébkový přepínač
Podtrhnout	bool	Přepínač

MarginPadding Odstup okraje určuje zarovnání textu ve vizuálním prvku. Skládá se z následujících vlastností:
- Vlevo
- Vpravo
- Vrchol
- Dno
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í

Vlevo Číselný NumUpDown

Vpravo Číselný NumUpDown

Vrchol Číselný NumUpDown

Dno Číselný NumUpDown

Vlastnost	Typ schopností	Typ formátování
Vlevo	Číselný	NumUpDown
Vpravo	Číselný	NumUpDown
Vrchol	Číselný	NumUpDown
Dno	Číselný	NumUpDown

Prostředky GitHubu

Všechna rozhraní modelu formátování najdete v GitHubu – microsoft/powerbi-visuals-api: rozhraní API vlastních vizuálů Power BI v 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 modelu formátování vizuálů Power BI
Příklad uživatelského vizuálu SampleBarChart, který používá rozhraní API verze 5.1.0 a implementuje getFormattingModel pomocí nových utilit modelu formátování na GitHubu – microsoft/PowerBI-visuals-sampleBarChart: Uživatelský vizuál pruhového grafu pro výukový materiál.

Máte další otázky? Požádejte komunitu Power BI o pomoc

Sdílet prostřednictvím

Podokno formátování ve vizuálech na míru Power BI

Vytvořte vizuál podporující nové podokno formátu

Příklad implementace modelu formátování

Vlastnosti formátování mapy

Formátovací model

Formátování součástí modelu

Vlastnosti formátování podokna vizualizace

Vlastnosti složeného řezu

Prostředky GitHubu

Váš názor

Další materiály

Sdílet prostřednictvím

Podokno formátování ve vizuálech na míru Power BI

Vytvořte vizuál podporující nové podokno formátu

Příklad implementace modelu formátování

Vlastnosti formátování mapy

Formátovací model

Formátování součástí modelu

Vlastnosti formátování podokna vizualizace

Vlastnosti složeného řezu

Prostředky GitHubu

Související obsah

Váš názor

Další materiály