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 apiVersionsú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:

1. 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 a descriptionsú teraz voliteľné.

2. 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).

3. Implementujte rozhranie getFormattingModel API v triede vlastného vizuálu, ktorá vráti model formátovania vlastného vizuálu. (Toto rozhranie API nahrádza enumerateObjectInstances 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:

1. Nastavte hodnotu v súbore apiVersion pbiviz.json na alebo novšiu 5.1 verziu.

2. 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ázvu objectName 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	Číselné Celé číslo	NumUpDown Jazdec
Zoznam enumerácií	enumerácia:[]	ItemDropdown (Položka) ItemFlagsSelection Automatické rozbaľovacie okno Automatické označenieVýber * Pozri poznámku nižšie
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	TextInput Textarea

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