Personalizzare il riquadro formato negli oggetti visivi personalizzati di Power BI

A partire dall'API versione 5.1, gli sviluppatori possono creare oggetti visivi che usano il nuovo riquadro Formato alimentazione. Gli sviluppatori possono definire le schede e le relative categorie per qualsiasi proprietà nell'oggetto visivo personalizzato, semplificando l'uso di questi oggetti visivi da parte degli autori di report.

La nuova API usa il metodo FormattingModel per personalizzare parti del formato e dei riquadri di analisi.

Suggerimento

Il getFormattingModel metodo sostituisce il enumerateObjectInstances metodo nelle versioni precedenti dell'API.

Restituisce getFormattingModel un oggetto FormattingModel che definisce l'aspetto del riquadro di formattazione e analisi dell'oggetto visivo.

Oltre a tutte le funzionalità del riquadro di formattazione precedenti, il nuovo modello di formattazione supporta nuove funzionalità del riquadro di formato, nuove proprietà e nuove gerarchie.

Per eseguire l'aggiornamento all'API apiVersion versione 5.1+, impostare nel file pbiviz.json su 5.1 o versione successiva ed eseguire una delle operazioni seguenti:

• Usare formattingmodel util. (consigliato).
• Senza questa utilità, usare solo le API in base al metodo seguente.

Creare un oggetto visivo che supporti il nuovo riquadro formato

Per creare un oggetto visivo personalizzato che usa il nuovo riquadro formato:

1. Definire tutti i valori personalizzabili objects nel file capabilities.json .
   Per ogni oggetto sono necessarie le proprietà seguenti:

   • nome oggetto
   • Nome della proprietà
   • tipo di proprietà

   Tutte le altre proprietà, incluse DisplayName e description, sono ora facoltative.

2. Compilare l'oggetto visivo personalizzato FormattingModel. Definire le proprietà del modello di formattazione visiva personalizzato e compilarlo usando codice (non JSON).

3. Implementare l'API getFormattingModel nella classe visiva personalizzata che restituisce un modello di formattazione visiva personalizzato. Questa API sostituisce l'oggetto enumerateObjectInstances usato nelle versioni precedenti.

Proprietà di formattazione mappa

Se si dispone di un oggetto visivo personalizzato creato con un'API precedente e si vuole eseguire la migrazione al nuovo riquadro di formato o se si sta creando un nuovo oggetto visivo personalizzato:

1. Impostare nel apiVersionfile pbiviz.json su 5.1 o versione successiva.

2. Per ogni nome di oggetto e nome della proprietà in capabilities.json, creare una proprietà di formattazione corrispondente. La proprietà di formattazione deve avere un descrittore che contiene un objectName oggetto e propertyName che corrisponde al nome dell'oggetto e al nome della proprietà in capabilities.json.

Le objects proprietà nel file delle funzionalità hanno ancora lo stesso formato e non devono essere modificate.

Ad esempio, se l'oggetto circle nel file capabilities.json è definito come segue:

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

La proprietà di formattazione nel modello deve essere di tipo ColorPicker e avere un aspetto simile al seguente:

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

Se si verifica una delle condizioni seguenti, verrà visualizzato un errore:

• Il nome dell'oggetto o della proprietà nel file delle funzionalità non corrisponde a quello nel modello di formattazione
• Il tipo di proprietà nel file delle funzionalità non corrisponde al tipo nel modello di formattazione

Modello di formattazione

Il modello di formattazione è il percorso in cui si descrivono e si personalizzano tutte le proprietà del riquadro formato.

Formattazione dei componenti del modello

Nel nuovo modello di formattazione i componenti delle proprietà vengono raggruppati in categorie logiche e sottocategorie. Questi gruppi semplificano l'analisi del modello. Esistono i cinque componenti di base, dal più grande al più piccolo:

• Modello di formattazione
  Contenitore del riquadro più grande, usato per la formattazione dell'interfaccia anteriore del riquadro. Contiene un elenco di schede di formattazione.

• Scheda formattazione
  Contenitore di raggruppamento delle proprietà di primo livello per la formattazione delle proprietà. Ogni scheda è costituita da uno o più gruppi di formattazione, come illustrato di seguito.

  

• Gruppo di formattazione
  Contenitore di raggruppamento delle proprietà a livello secondario. Il gruppo di formattazione viene visualizzato come contenitore di raggruppamento per la formattazione delle sezioni.

  

• Formattazione della sezione
  Contenitore di proprietà. Esistono due tipi di sezioni:

  • Sezione semplice: contenitore di proprietà singolo
  • Sezione composita: più contenitori di proprietà correlati raggruppati in una sezione di formattazione

  L'immagine seguente mostra i diversi tipi di sezioni. "Font" è una sezione composita costituita da famiglie di caratteri, dimensioni e grassetto, corsivo e sottolineatura. "Colore", "unità di visualizzazione" e le altre sezioni sono sezioni semplici con un componente ciascuno.

  

Proprietà di formattazione del riquadro visualizzazione

Ogni proprietà nel modello di formattazione deve corrispondere al tipo di oggetto e nel file capabilities.json .

La tabella seguente mostra i tipi di proprietà di formattazione nel file capabilities.json e la relativa classe di tipo corrispondente nelle proprietà moderne del modello di formattazione:

Tipo	Tipo valore funzionalità	Formatting, proprietà
Boolean	Bool	ToggleSwitch
Numero	numeric Intero	NumUpDown Dispositivo di scorrimento
Elenco di enumerazione	enumerazione:[]	ItemDropdown ItemFlagsSelection AutoDropdown AutoFlagsSelection * Vedere la nota seguente
Color	Riempi	ColorPicker
Sfumatura	Fillrule	GradientBar: il valore della proprietà deve essere costituito da: minValue[,midValue],maxValue
Testo	Testo	TextInput Textarea

Funzionalità di formattazione di oggetti

Tipo	Tipo valore funzionalità	Formatting, proprietà
Dimensioni carattere	FontSize	NumUpDown
Famiglia di caratteri	FontFamily	FontPicker
Allineamento linea	Allineamento	AlignmentGroup
Unità di visualizzazione etichetta	LabelDisplayUnits	AutoDropDown

^* La proprietà di formattazione dell'elenco di enumerazione è diversa nel modello di formattazione e nel file delle funzionalità.

• Dichiarare le proprietà seguenti nella classe delle impostazioni di formattazione, incluso l'elenco di elementi di enumerazione:

  • ItemDropdown
  • ItemFlagsSelection

• Dichiarare le proprietà seguenti nella classe delle impostazioni di formattazione, senza l'elenco di elementi di enumerazione. Dichiarare l'elenco di elementi di enumerazione in capabilities.json nell'oggetto appropriato. Questi tipi sono gli stessi delle versioni precedenti dell'API:

  • AutoDropdown
  • AutoFlagSelection

Proprietà della sezione composita

Una sezione composita di formattazione è una sezione di formattazione che contiene più proprietà correlate tutte insieme.

Per il momento sono disponibili due tipi di sezione compositi:

• FontControl
  In questo modo tutte le proprietà correlate ai tipi di carattere vengono unite. È costituito dalle proprietà seguenti:

  • Famiglia di caratteri
  • Dimensioni carattere
  • Grassetto [facoltativo]
  • Corsivo [facoltativo]
  • Sottolineatura [facoltativo]

  

  Ognuna di queste proprietà deve avere un oggetto corrispondente nel file delle funzionalità:

  Proprietà	Tipo di funzionalità	Tipo di formattazione
  Famiglia di caratteri	Formattazione: { fontFamily}	FontPicker
  Dimensioni carattere	Formattazione: {fontSize}	NumUpDown
  Grassetto	Bool	ToggleSwitch
  Italic	Bool	ToggleSwitch
  Sottolineato	Bool	ToggleSwitch

• MarginPadding Margin padding determina l'allineamento del testo nell'oggetto visivo. È costituito dalle proprietà seguenti:

  • Sinistra
  • Right
  • In alto
  • In basso

  Ognuna di queste proprietà deve avere un oggetto corrispondente nel file delle funzionalità:

  Proprietà	Tipo di funzionalità	Tipo di formattazione
  Sinistra	Numerico	NumUpDown
  Right	Numerico	NumUpDown
  In alto	Numerico	NumUpDown
  In basso	Numerico	NumUpDown

Esempio: Formattazione di una scheda dati

In questo esempio viene illustrato come creare un modello di formattazione visiva personalizzato con una scheda.
La scheda ha due gruppi:

• Gruppo di controlli carattere con una proprietà composita
  • Controllo carattere
• Gruppo di progettazione dei dati con due proprietà semplici
  • Colore carattere
  • Allineamento linea

Aggiungere prima di tutto gli oggetti al file delle funzionalità:

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

Creare quindi il 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;
    }

Ecco il riquadro risultante:

Reimpostare le impostazioni predefinite

Il nuovo riquadro formato ha la possibilità di reimpostare tutti i valori delle proprietà della scheda di formattazione per impostazione predefinita facendo clic sul pulsante Ripristina impostazioni predefinite visualizzato nella scheda aperta.

Per abilitare questa funzionalità, aggiungere un elenco di descrittori di proprietà della scheda di formattazione alla scheda revertToDefaultDescriptorsdi formattazione . L'esempio seguente illustra come aggiungere la reimpostazione al pulsante predefinito :

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

L'aggiunta revertToDefaultDescriptors alle schede di formattazione consente anche di reimpostare tutte le proprietà delle schede di formattazione contemporaneamente facendo clic sul pulsante reimposta tutte le impostazioni sul pulsante predefinito nella barra superiore del riquadro formato:

Selettore di proprietà di formattazione

Il selettore facoltativo nel descrittore delle proprietà di formattazione determina dove ogni proprietà è associata in dataView. Sono disponibili quattro opzioni distinte. Informazioni su di essi nei tipi di selettori di oggetti.

Localizzazione

Per altre informazioni sulla funzionalità di localizzazione e per configurare un ambiente di localizzazione, vedere Aggiungere la lingua locale all'oggetto visivo di Power BI Usare gestione localizzazione per formattare i componenti da localizzare:

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

Per localizzare la formattazione delle utilità del modello di formattazione della localizzazione.

Risorse di GitHub

• Tutte le interfacce del modello di formattazione sono disponibili in GitHub - microsoft/powerbi-visuals-api: API degli oggetti visivi personalizzati di Power BI in "formatting-model-api.d.ts"

• È consigliabile usare il nuovo modello di formattazione utils in GitHub - microsoft/powerbi-visuals-utils-formattingmodel: Helper del modello di formattazione degli oggetti visivi di Power BI

• È possibile trovare un esempio di sampleBarChart visivo personalizzato che usa l'API versione 5.1.0 e implementa getFormattingModel usando il nuovo modello di formattazione utils in GitHub - microsoft/PowerBI-visuals-sampleBarChart: Grafico a barre personalizzato per l'esercitazione.

Contenuto correlato

Altre domande? Chiedere al Community di Power BI