Esercitazione: Aggiungere opzioni di formattazione all'oggetto visivo Circle Card

Quando si crea un oggetto visivo, è possibile aggiungere opzioni per personalizzarne le proprietà. Alcuni degli elementi che possono essere personalizzati includono:

• Titolo
• Background
• Border
• Shadow
• Colori

In questa esercitazione apprenderai a:

• Aggiungere proprietà di formattazione all'oggetto visivo.
• Creare un pacchetto dell'oggetto visivo
• Importare l'oggetto visivo personalizzato in un report di Power BI Desktop o del servizio

Prerequisito

Questa esercitazione illustra come aggiungere proprietà di formattazione comuni a un oggetto visivo. L'oggetto visivo Circle card verrà usato come esempio. Aggiungeremo la possibilità di modificare il colore e lo spessore del cerchio. Se la cartella del progetto Circle card creata in tale esercitazione non è disponibile, ripetere l'esercitazione prima di continuare.

Aggiunta di opzioni di formattazione

1. In PowerShell passare alla cartella del progetto circle card e avviare l'oggetto visivo circle card. L'oggetto visivo è ora in esecuzione mentre è ospitato nel computer.

   pbiviz start
   

2. In Power BI selezionare il pannello Formato.

   Verranno visualizzate opzioni di formattazione generali, ma non opzioni di formattazione visiva.

   

3. In Visual Studio Code aprire il capabilities.json file.

4. Prima della matrice dataViewMappings , aggiungere oggetti.

   "objects": {},
   

   

5. Salvare il file capabilities.json.

6. In Power BI esaminare di nuovo le opzioni di formattazione.

   Nota

   Se le opzioni di formattazione non vengono modificate, selezionare Ricarica oggetto visivo personalizzato.

   

7. Impostare l'opzione Titolo su No. Si noti che l'oggetto visivo non visualizza più il nome della misura nell'angolo superiore sinistro.

   

   

Aggiunta di opzioni di formattazione personalizzate

Aggiungere ora un nuovo gruppo denominato colore per configurare il colore del cerchio e lo spessore del contorno del cerchio.

1. In PowerShell immettere CTRL+C per arrestare l'oggetto visivo personalizzato.

2. Nel file di capabilities.json Visual Studio Code inserire il frammento JSON seguente negli oggetti etichettati.

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

   Questo frammento JSON descrive un gruppo denominato circle, costituito da due variabili, circleColor e circleThickness.

3. Salvare il file capabilities.json.

4. Nel riquadro Explorer passare alla cartella src e quindi selezionare settings.ts. Questo file rappresenta le impostazioni per l'oggetto visivo iniziale.

5. settings.ts Nel file sostituire le righe di importazione e due classi con il codice seguente.

   import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";
   
   import FormattingSettingsCard = formattingSettings.SimpleCard;
   import FormattingSettingsSlice = formattingSettings.Slice;
   import FormattingSettingsModel = formattingSettings.Model;
   
   export class CircleSettings extends FormattingSettingsCard{
       public circleColor = new formattingSettings.ColorPicker({
           name: "circleColor",
           displayName: "Color",
           value: { value: "#ffffff" },
           visible: true
       });
   
       public circleThickness = new formattingSettings.NumUpDown({
           name: "circleThickness",
           displayName: "Thickness",
           value: 2,
           visible: true
       });
   
       public name: string = "circle";
       public displayName: string = "Circle";
       public visible: boolean = true;
       public slices: FormattingSettingsSlice[] = [this.circleColor, this.circleThickness]
   }
   
   export class VisualSettings extends FormattingSettingsModel {
       public circle: CircleSettings = new CircleSettings();
       public cards: FormattingSettingsCard[] = [this.circle];
   }
   

   Questo modulo definisce le due classi. La classe Circle Impostazioni definisce due proprietà con nomi che corrispondono agli oggetti definiti nel file capabilities.json (circleColor e circleThickness) e imposta i valori predefiniti. La classe Visual Impostazioni definisce l'oggetto circle in base alle proprietà descritte nel capabilities.json file.

6. Salvare il file settings.ts.

7. Apri il file visual.ts.

8. visual.ts Nel file importare :

   import { VisualSettings } from "./settings";
   import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";
   

   e nella classe Visual aggiungere le proprietà seguenti:

   private visualSettings: VisualSettings;
   private formattingSettingsService: FormattingSettingsService;
   
   

   Questa proprietà archivia un riferimento all'oggetto Visual Impostazioni, che descrive le impostazioni dell'oggetto visivo.

9. Nella classe Visual inserire quanto segue come prima riga del costruttore:

   this.formattingSettingsService = new FormattingSettingsService();
   

10. Nella classe Visual aggiungere il metodo seguente dopo il metodo update.

    public getFormattingModel(): powerbi.visuals.FormattingModel {
        return this.formattingSettingsService.buildFormattingModel(this.visualSettings);
    }
    

    Questa funzione viene chiamata in ogni rendering del riquadro di formattazione. Consente di selezionare gli oggetti e le proprietà che si desidera esporre agli utenti nel riquadro delle proprietà.

11. Nel metodo update, dopo la dichiarazione della variabile radius, aggiungere il codice seguente.

    this.visualSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualSettings, options.dataViews);
    this.visualSettings.circle.circleThickness.value = Math.max(0, this.visualSettings.circle.circleThickness.value);
    this.visualSettings.circle.circleThickness.value = Math.min(10, this.visualSettings.circle.circleThickness.value);
    

    Questo codice recupera le opzioni di formato. Modifica qualsiasi valore passato nella proprietà circleThickness e lo converte in un numero compreso tra zero e 10.

    

12. Nell'elemento circle modificare i valori passati allo stile di riempimento e allo stile di larghezza del tratto come indicato di seguito:

    .style("fill", this.visualSettings.circle.circleColor.value.value)
    

    .style("stroke-width", this.visualSettings.circle.circleThickness.value)
    

    

13. Salvare il file visual.ts.

14. In PowerShell avviare l'oggetto visivo.

    pbiviz start
    

15. In Power BI, sulla barra degli strumenti mobile sopra l'oggetto visivo, selezionare Attiva/Disattiva ricaricamento automatico.

    

16. Nelle opzioni di formato dell'oggetto visivo espandere Circle.

    

    Modificare l'opzione colore e spessore .

Modificare l'opzione spessore in un valore minore di zero e un valore maggiore di 10. Si noti quindi che l'oggetto visivo aggiorna il valore a un valore minimo o massimo tollerabile.

Debug

Per suggerimenti sul debug dell'oggetto visivo personalizzato, vedere la guida al debug.

Creazione del pacchetto dell'oggetto visivo personalizzato

Ora che l'oggetto visivo è stato completato e pronto per l'uso, è possibile crearne il pacchetto. Un oggetto visivo in pacchetto può essere importato in report o servizi di Power BI per essere usato e apprezzato da altri utenti.

Quando l'oggetto visivo è pronto, seguire le istruzioni riportate in Creare un oggetto visivo di Power BI e quindi condividerlo con altri utenti in modo che possano importarlo e usarlo.

Contenuto correlato

• Creare un oggetto visivo grafico a barre di Power BI
• Informazioni su come eseguire il debug di un oggetto visivo di Power BI creato
• Struttura del progetto degli oggetti visivi di Power BI