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 Power. Gli sviluppatori possono definire le schede e le relative categorie per qualsiasi proprietà nell'oggetto visivo personalizzato, semplificando l'uso di tali oggetti visivi da parte degli autori di report.

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

getFormattingModel restituisce un FormattingModel che definisce l'aspetto del riquadro 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 Formato, nuove proprietà e nuove gerarchie.

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

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

Creare un oggetto visivo che supporti il nuovo riquadro format

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

1. Definire tutte le opzioni objects personalizzabili nel file capabilities.json.
   Per ogni oggetto sono necessarie le proprietà seguenti:

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

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

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

3. Implementare l'API getFormattingModel nella classe dell'oggetto visivo personalizzato che restituisce un modello di formattazione dell'oggetto visivo personalizzato. (Questa API sostituisce enumerateObjectInstances, utilizzato 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 formato o se si sta creando un nuovo oggetto visivo personalizzato:

1. Impostare apiVersion nel file pbiviz.json su 5.1 o versione successiva.

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

Le proprietà objects 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, comparirà un errore:

• Il nome oggetto o proprietà nel file delle funzionalità non corrisponde a quello nel modello di formattazione
• Il tipo di proprietà nel file delle funzionalità non corrisponde a quello 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.

Componenti del modello di formattazione

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

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

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

  

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

  

• Sezione di formattazione
  Contenitore di proprietà. Esistono due tipi di sezione:

  • 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 opzioni per il grassetto, il corsivo e la 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 nel file capabilities.json.

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

Funzionalità di formattazione di oggetti

^* 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 degli elementi di enumerazione:

  • ItemDropdown
  • ItemFlagsSelection

• Dichiarare le proprietà seguenti nella classe delle impostazioni di formattazione, senza l'elenco degli elementi di enumerazione. Dichiarare l'elenco degli elementi di enumerazione in capabilities.json sotto l'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 composita:

• FontControl
  Riunisce tutte le proprietà correlate al tipo di carattere. È costituito dalle seguenti proprietà:

  • 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 Il padding margin determina l'allineamento del testo nell'oggetto visivo. È costituito dalle seguenti proprietà:

  • 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 di un oggetto visivo personalizzato con una scheda.
La scheda ha due gruppi:

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

Aggiungere innanzitutto 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
                        }
                    }
                }
            }
        }
    }

Poi creare 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:

Ripristinare le impostazioni predefinite

Il nuovo riquadro formato ha la possibilità di ripristinare tutti i valori predefiniti delle proprietà della scheda di formattazione facendo clic sul pulsante Ripristina impostazioni predefinite che compare nella scheda aperta.

Per abilitare questa funzionalità, aggiungere un elenco di descrittori di proprietà della scheda di formattazione alla scheda di formattazione revertToDefaultDescriptors. L'esempio seguente illustra come aggiungere il pulsante Ripristina impostazioni predefinite:

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 di revertToDefaultDescriptors alle schede di formattazione consente anche di reimpostare tutte le proprietà delle schede di formattazione contemporaneamente facendo clic sul pulsante Ripristina tutte le impostazioni predefinite 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 diverse. Sono disponibili informazioni a riguardo nei tipi di selettori di oggetti.

Localizzazione

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

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

Per localizzare le utilità del modello di formattazione localizzazione delle utilità di formattazione.

Risorse di GitHub

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

• È consigliabile usare la nuova utilità del modello di formattazione in GitHub - microsoft/powerbi-visuals-utils-formattingmodel: helper modello di formattazione degli oggetti visivi di Power BI

• È possibile trovare un esempio di oggetto visivo personalizzato SampleBarChart che usa l'API versione 5.1.0 e implementa getFormattingModel usando le nuove utilità del modello di formattazione in GitHub - microsoft/PowerBI-visuals-sampleBarChart: oggetto visivo personalizzato grafico a barre per l'esercitazione.

Contenuto correlato

Altre domande? Inviare una domanda alla community di Power BI