Tabla 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ú novej tably formátu služby 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.

Funkcia getFormattingModel vráti 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.

Vytvorenie vizuálu podporujúceho novú tablu formátu

Všeobecné kroky na pridanie novej podpory tably formátu do vlastného vizuálu:

1. Nastavte apiVersion v súbore pbiviz.json na 5.1 alebo novšie verzie.

2. Definujte všetky prispôsobiteľné objects v súbore capabilities.json. Tieto objekty sú potom primapované k vlastnostiam tably formátovania. 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 a descriptionsú teraz voliteľné.

3. Vytvorte vlastný vizuál FormattingModel vykonaním jedného:

   • Použite pomôcku formattingmodel. (Odporúčaná)
   • Bez tejto pomôcky používajte iba rozhrania API.

Definujte vlastnosti svojho modelu formátovania vlastného vizuálu a vytvorte ho pomocou kódu (nie JSON).

4. Implementujte getFormattingModel API do triedy vlastného vizuálu, ktorá vracia model formátovania vlastného vizuálu. (Toto rozhranie API nahrádza enumerateObjectInstances, ktorý bol použitý v predchádzajúcich verziách).

Príklad implementácie modelu formátovania

• Model formátovania pomocou pomôcky formattingmodel príklad. (Odporúčaná)
• Model formátovania, ktorý používa iba rozhrania API príklad.

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:

1. Nastavte apiVersion v súbore pbiviz.json na 5.1 alebo novšie verzie.

2. Pre každý názov objektu a názov vlastnosti v capabilities.jsonvytvorte zodpovedajúcu vlastnosť formátovania. Vlastnosť formátovania by mala mať popisovač, ktorý obsahuje objectName a propertyName, ktorý zodpovedá názvu objektu a názvu vlastnosti v 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 circle v súbore 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 splnená 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 predného rozhrania tably. Obsahuje zoznam kariet formátovania.

• karta Formátovanie Kontajner vlastností najvyššej úrovne, ktorý zoskupuje vlastnosti formátovania. Každá karta pozostáva z jednej alebo viacerých skupín formátovania, ako je to znázornené tu.

  

• skupiny formátovania
  Kontajner na zoskupenie vlastností druhej úrovne. Skupina formátovania sa zobrazí ako kontajner na zoskupenie na formátovanie rýchlych filtrov.

  

• kontajnera formátovania
  Kontajner na zoskupenie vlastností druhej úrovne. Formátovanie kontajnera formátovania zoskupuje výseky na samostatné položky kontajnera a umožňuje prepínať medzi nimi pomocou rozbaľovacieho zoznamu.

  

• rýchleho filtra formátovania
  Kontajner vlastností. Existujú dva typy rýchlych filtrov:

  • Jednoduchý výsek: Kontajner s jednotlivými vlastnosťami
  • zložený rýchly filter: Viaceré súvisiace kontajnery vlastností zoskupené do jedného výseku 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. "Color", "display units" a ostatné rýchle filtre 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.

V nasledujúcej tabuľke sú uvedené typy vlastností formátovania v capabilities.json súbore a ich zodpovedajúcu triedu typu v moderných vlastnostiach modelu formátovania:

Možnosti formátovania objektov

^* 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 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:

  Majetok	Typ možností	Typ formátovania
  Skupina písem	Formátovanie: { fontFamily}	FontPicker
  Veľkosť písma	Formátovanie: {fontSize}	NumUpDown
  Smelý	Bool	PrepínačPrepínač
  Kurzíva	Bool	PrepínačPrepínač
  Podčiarknuť	Bool	PrepínačPrepínač

• odsadenie okrajov okraje určuje zarovnanie textu vo vizuáli. Pozostáva z nasledujúcich vlastností:

  • Vľavo
  • Doprava
  • Vrchol
  • Dno

  Každá z týchto vlastností by mala mať v súbore možností zodpovedajúci objekt:

  Majetok	Typ možností	Typ formátovania
  Vľavo	Numerický	NumUpDown
  Doprava	Numerický	NumUpDown
  Vrchol	Numerický	NumUpDown
  Dno	Numerický	NumUpDown

Zdroje GitHubu

• Všetky rozhrania modelu formátovania nájdete v službe GitHub – 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 na lokalite GitHub – microsoft/powerbi-visuals-utils-formattingmodel: Pomôcky pre pomocné pomôcky modelu pre vizuály služby Power BI

• Môžete nájsť príklad vlastného vizuálu SampleBarChart, ktorý používa rozhranie API verzie 5.1.0 a implementuje getFormattingModel pomocou nových pomôcok modelu formátovania na GitHub - microsoft/PowerBI-visuals-sampleBarChart: Vlastný vizuál pruhového grafu pre kurz.

Súvisiaci obsah

Máte ďalšie otázky? spýtajte sa komunity Power BI