A Formátum panel testreszabása egyéni Power BI-vizualizációkban

Az API 5.1-es verziójától kezdve a fejlesztők létrehozhatnak olyan vizualizációkat, amelyek az új Power format panelt használják. A fejlesztők az egyéni vizualizációk bármely tulajdonságához definiálhatják a kártyákat és a kategóriáikat, így a jelentéskészítők könnyebben használhatják ezeket a vizualizációkat.

Az új API a FormattingModel metódust használja a formátum és az elemzési panelek egyes részeinek testreszabásához.

Tipp.

A getFormattingModel metódus a korábbi API-verziókban lecseréli a enumerateObjectInstances metódust.

A getFormattingModel függvény egy olyan értéket FormattingModel ad vissza, amely meghatározza a vizualizáció formázási és elemzési paneljének megjelenését.

Az új formázási modell a régi formázási panel képességei mellett új formázási panel-képességeket, új tulajdonságokat és új hierarchiákat is támogat.

Az API 5.1+-os verziójára való frissítéshez állítsa be a apiVersion pbiviz.json fájlban lévő fájlt vagy újabb verziót5.1, és tegye az alábbiak egyikét:

• Formázásmodell util használata. (Ajánlott)
• E nélkül a következő módszer szerint csak API-kat használjon.

Az új formátumpanelt támogató vizualizáció létrehozása

Az új formátumpanelt használó egyéni vizualizáció létrehozása:

1. Definiálja a capabilities.json fájlban található összes testreszabható objects fájlt.
   Minden objektumhoz a következő tulajdonságok szükségesek:

   • objektum neve
   • tulajdonság neve
   • tulajdonságtípus

   Most már nem kötelező minden más tulajdonság, beleértve DisplayName az és descriptionazokat is.

2. Hozza létre az egyéni vizualizációformázásmodellt. Határozza meg az egyéni vizualizációformázási modell tulajdonságait, és hozza létre kóddal (nem JSON használatával).

3. Implementálja az getFormattingModel API-t az egyéni vizualizációs osztályban, amely egyéni vizualizációformázási modellt ad vissza. (Ez az API lecseréli az enumerateObjectInstances előző verziókban használtakat).

Térképformázási tulajdonságok

Ha egy régebbi API-val létrehozott egyéni vizualizációt szeretne áttelepíteni az új formátumpanelre, vagy ha új egyéni vizualizációt hoz létre:

1. Állítsa be a apiVersion pbiviz.json fájlban a következőre vagy újabbra5.1.

2. A capabilities.json minden objektumnévhez és tulajdonságnévhez hozzon létre egy megfelelő formázási tulajdonságot. A formázási tulajdonságnak rendelkeznie kell egy leíróval, amely tartalmaz egy objectNamepropertyName olyan leírót, amely megfelel a capabilities.json objektumnevének és tulajdonságnevének.

A objects képességfájl tulajdonságai továbbra is ugyanazzal a formátummal rendelkeznek, és nem kell módosítani.

Ha például a circle capabilities.json fájl objektuma a következőképpen van definiálva:

"objects": {
    "circle": {
        "properties": {
            "circleColor": {
                "type": {
                    "fill": {
                        "solid": {
                            "color": true
                        }
                    }
                  }
          },
        }
      }
    }

A modell formázási tulajdonságának a következőképpen ColorPicker kell kinéznie:

control: {
    type: "ColorPicker",
    properties: {
        descriptor: {
            objectName: "circle",
            propertyName: "circleColor"
        },
        value: {
            value: this.visualSettings.circle.circleColor
        }
    }
}

Ha az alábbi feltételek egyike teljesül, hibaüzenet jelenik meg:

• A képességfájl objektum- vagy tulajdonságneve nem egyezik meg a formázási modellben szereplővel
• A képességfájl tulajdonságtípusa nem egyezik a formázási modell típusával

Formázási modell

A formázási modellben írja le és szabja testre a formázási panel összes tulajdonságát.

Modellösszetevők formázása

Az új formázási modellben a tulajdonságösszetevők logikai kategóriákba és alkategóriákba vannak csoportosítva. Ezek a csoportok megkönnyítik a modell vizsgálatát. Az öt alapösszetevő a legnagyobbtól a legkisebbig:

• Formázási modell
  A legnagyobb paneltároló, amely a panel előtéri felületének formázására szolgál. A formázási kártyák listáját tartalmazza.

• Formázási kártya
  A legfelső szintű tulajdonságok csoportosítása tároló formázási tulajdonságokhoz. Minden kártya egy vagy több formázási csoportból áll, az itt látható módon.

  

• Formázási csoport
  A másodlagos szintű tulajdonságok csoportosítási tárolója. A formázási csoport csoportosítási tárolóként jelenik meg a szeletek formázásához.

  

• Formázási szelet
  Tulajdonságtároló. Kétféle szelet létezik:

  • Egyszerű szelet: Egyéni tulajdonságtároló
  • Összetett szelet: Több kapcsolódó tulajdonságtároló egyetlen formázási szeletbe csoportosítva

  Az alábbi képen a különböző típusú szeletek láthatók. A "Betűtípus" egy összetett szelet, amely betűcsaládból, méretből, félkövér, dőlt és aláhúzott kapcsolókból áll. A "Szín", a "megjelenítési egységek" és a többi szelet egy-egy összetevővel rendelkező egyszerű szeletek.

  

Vizualizáció panel formázási tulajdonságai

A formázási modell minden tulajdonságának meg kell egyeznie a capabilities.json fájl objektumtípusával.

Az alábbi táblázat a capabilities.json fájl formázási tulajdonságtípusait és a modern formázási modell tulajdonságainak megfelelő típusosztályát mutatja be:

Típus	Képességek értéktípusa	Formázás tulajdonság
Logikai	Bool	ToggleSwitch
Szám	Numerikus Egész	NumUpDown Csúszka
Enumerálási lista	enumerálás:[]	ItemDropdown ItemFlagsSelection AutoDropdown AutoFlagsSelection * Lásd az alábbi megjegyzést
Szín	Kitöltés	Colorpicker
Színátmenet	FillRule	Színátmenetsáv: a tulajdonságértéknek sztringnek kell lennie, amely a következőkből áll: minValue[,midValue],maxValue
SMS	SMS	TextInput Textarea

Képességek az objektumok formázására

Típus	Képességek értéktípusa	Formázás tulajdonság
Betűméret	FontSize	NumUpDown
Betűcsalád	FontFamily	FontPicker
Vonal igazítása	Megoldás	Igazításcsoport
Címkemegjelenítési egységek	LabelDisplayUnits	AutoDropDown

^* Az enumerálási lista formázási tulajdonsága eltér a formázási modellben és a képességfájlban.

• Deklarálja a következő tulajdonságokat a formázási beállítások osztályban, beleértve az enumerálási elemek listáját:

  • ItemDropdown
  • ItemFlagsSelection

• Deklarálja a következő tulajdonságokat a formázási beállítások osztályban az enumerálási elemek listája nélkül. Deklarálja az enumerálási elemek listáját a capabilities.json fájlban a megfelelő objektum alatt. (Ezek a típusok ugyanazok, mint az előző API-verziókban):

  • AutoDropdown
  • AutoFlagSelection

Összetett szelet tulajdonságai

Az összetett formázási szeletek olyan formázási szeletek, amelyek egyszerre több kapcsolódó tulajdonságot tartalmaznak.

Jelenleg két összetett szelettípusunk van:

• FontControl
  Így a betűtípussal kapcsolatos összes tulajdonság együtt marad. A következő tulajdonságokból áll:

  • Betűcsalád
  • Betűméret
  • Félkövér [nem kötelező]
  • Dőlt [nem kötelező]
  • Aláhúzás [nem kötelező]

  

  Mindegyik tulajdonságnak rendelkeznie kell egy megfelelő objektummal a képességfájlban:

  Tulajdonság	Képességek típusa	Formázás típusa
  Betűcsalád	Formázás: { fontFamily}	FontPicker
  Betűméret	Formázás: {fontSize}	NumUpDown
  Félkövér	Bool	ToggleSwitch
  Italic	Bool	ToggleSwitch
  Aláhúzott	Bool	ToggleSwitch

• A MarginPadding Margin padding a vizualizáció szövegének igazítását határozza meg. A következő tulajdonságokból áll:

  • Left
  • Right
  • Felső
  • Alsó

  Mindegyik tulajdonságnak rendelkeznie kell egy megfelelő objektummal a képességfájlban:

  Tulajdonság	Képességek típusa	Formázás típusa
  Left	Numerikus	NumUpDown
  Right	Numerikus	NumUpDown
  Felső	Numerikus	NumUpDown
  Alsó	Numerikus	NumUpDown

Példa: Adatkártya formázása

Ebben a példában bemutatjuk, hogyan hozhat létre egyéni vizualizációformázási modellt egy kártyával.
A kártya két csoportból áll:

• Betűtípus-vezérlőcsoport egyetlen összetett tulajdonsággal
  • Betűtípus-vezérlő
• Adattervező csoport két egyszerű tulajdonsággal
  • Betűszín
  • Vonal igazítása

Először adjon hozzá objektumokat a képességfájlhoz:

"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
                        }
                    }
                }
            }
        }
    }

Ezután hozza létre a 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;
    }

Az eredményként kapott panel a következő:

Beállítások visszaállítása alapértelmezettre

Az új formázási panelen az összes formázási kártyatulajdonság értékét alaphelyzetbe állíthatja a megnyitott kártyán megjelenő Alaphelyzetbe állítás alapértelmezettre gombra kattintva.

A funkció engedélyezéséhez adja hozzá a formázási kártyatulajdonság-leírók listáját a kártya revertToDefaultDescriptorsformázásához. Az alábbi példa bemutatja, hogyan adhatja hozzá az alaphelyzetbe állítást az alapértelmezett gombhoz:

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 
    ]
};

A revertToDefaultDescriptors formázási kártyák hozzáadása lehetővé teszi az összes formázási kártyatulajdonság egyszerre történő visszaállítását is, ha a formázási panel felső sávján az összes beállítás alaphelyzetbe állítására kattint:

Formázási tulajdonságválasztó

A tulajdonságok leírójának formázásában választható választó határozza meg, hogy az egyes tulajdonságok hol vannak kötve a dataView-ban. Négy különböző lehetőség közül választhat. Ezekről az objektumválasztók típusaiban olvashat.

Honosítás

A honosítási funkcióval és a honosítási környezet beállításával kapcsolatos további információkért lásd : Helyi nyelv hozzáadása a Power BI-vizualizációhoz A honosítási kezelővel formázhatja a honosítani kívánt összetevőket:

displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");

A formázási modell utils formatting utils honosításának honosítása.

GitHub-erőforrások

• A formázási modell összes felülete megtalálható a GitHubon – microsoft/powerbi-visuals-api: Power BI custom visuals API in "formatting-model-api.d.ts"

• Javasoljuk, hogy a GitHubon használja az új formázási modelleket – microsoft/powerbi-visuals-utils-formattingmodel: Power BI-vizualizációk formázási modell segédeszközei

• Az 5.1.0-s API-verziót használó és az új formázási modell használatával implementálható getFormattingModel egyéni vizualizációkra találhat példát a GitHubon – microsoft/PowerBI-visuals-sampleBarChart: Bar Chart Custom Visual for tutorial.

Kapcsolódó tartalom

Van még esetleg kérdése? Kérdezze meg a Power BI-közösség