Esercitazione: Aggiunta di 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
  • Sfondo
  • Bordo
  • Ombreggiatura
  • Colori

In questa esercitazione verranno illustrate le procedure per:

  • Aggiungere proprietà di formattazione all'oggetto visivo.
  • Creare il pacchetto dell'oggetto visivo
  • Importare l'oggetto visivo personalizzato in un report di Power BI Desktop o di 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 non si dispone della cartella del progetto della scheda Circle creata in tale esercitazione, 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 in uso.

    pbiviz start
    
  2. In Power BI selezionare la pagina Formato.

    Verrà visualizzato il messaggio Le opzioni di formattazione non sono disponibili per questo oggetto visivo.

    Formatting paintbrush

    Se vengono visualizzate le opzioni di formattazione, ma non è possibile modificarle in Aggiunta di opzioni di formattazione personalizzate per personalizzarle.

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

  4. Prima della matrice dataViewMappings aggiungere objects (dopo la riga 8).

    "objects": {},
    

    Add objects

  5. Salvare il file.capabilities.json

  6. In Power BI accedere di nuovo alle opzioni di formattazione.

    Nota

    Se le opzioni di formattazione non sono ancora visualizzate selezionare Ricarica oggetto visivo personalizzato.

    View formatting options

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

    Tile option is off

    No name tile

Aggiunta di opzioni di formattazione personalizzate

Aggiungere ora un nuovo gruppo denominato colore per configurare il colore e la larghezza del cerchio.

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

  2. In Visual Studio Code, nel capabilities.json file inserire il frammento JSON seguente negli oggetti etichettati.

        {
            "circle": {
                "displayName": "Circle",
                "properties": {
                    "circleColor": {
                        "displayName": "Color",
                        "description": "The fill color of the circle.",
                        "type": {
                            "fill": {
                                "solid": {
                                    "color": true
                                }
                            }
                        }
                    },
                    "circleThickness": {
                        "displayName": "Thickness",
                        "description": "The circle thickness.",
                        "type": {
                            "numeric": true
                        }
                    }
                }
            }
        }
    

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

    Circle thickness code

  3. Salvare il file.capabilities.json

  4. Nel riquadro Esplora risorse passare alla cartella src e quindi selezionare settings.ts. Questo file rappresenta le impostazioni per l'oggetto visivo di partenza.

  5. settings.ts Nel file sostituire le due classi con il codice seguente.

    export class CircleSettings {
        public circleColor: string = "white";
        public circleThickness: number = 2;
    }
    export class VisualSettings extends DataViewObjectsParser {
        public circle: CircleSettings = new CircleSettings();
    }
    

    Module classes

    Questo modulo definisce le due classi. La classe CircleSettings definisce due proprietà con nomi che corrispondono agli oggetti definiti nel capabilities.json file (circleColor e circleThickness) e imposta anche i valori predefiniti. La classe VisualSettings eredita la classe DataViewObjectParser e aggiunge una proprietà denominata circle, che corrisponde all'oggetto definito nel capabilities.json file e restituisce un'istanza di CircleSettings.

  6. Salvare il file.settings.ts

  7. Aprire il file visual.ts.

  8. visual.ts Nel file importare VisualSettings, VisualObjectInstanceEnumeration e EnumerateVisualObjectInstancesOptions:

    import { VisualSettings } from "./settings";
    import VisualObjectInstanceEnumeration = powerbi.VisualObjectInstanceEnumeration;
    import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
    

    e nella classe Visual aggiungere la proprietà seguente:

    private visualSettings: VisualSettings;
    

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

    Add visual class

  9. Nella classe Visual aggiungere il metodo seguente prima del metodo update. Questo metodo viene usato per popolare le opzioni di formattazione.

    public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
        const settings: VisualSettings = this.visualSettings || <VisualSettings>VisualSettings.getDefault();
        return VisualSettings.enumerateObjectInstances(settings, options);
    }
    

    Questo metodo viene usato per popolare le opzioni di formattazione.

    Visual settings object

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

    this.visualSettings = VisualSettings.parse<VisualSettings>(dataView);
    
    this.visualSettings.circle.circleThickness = Math.max(0, this.visualSettings.circle.circleThickness);
    this.visualSettings.circle.circleThickness = Math.min(10, this.visualSettings.circle.circleThickness);
    

    Questo codice recupera le opzioni di formattazione. Modifica qualsiasi valore passato nella proprietà circleThickness, convertendolo in 0 se è negativo o 10 se si tratta di un valore maggiore di 10.

    Radius variable

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

    this.visualSettings.circle.circleColor
    
    this.visualSettings.circle.circleThickness
    

    Fills the circle element

  12. Salvare il file.visual.ts

  13. In PowerShell avviare l'oggetto visivo.

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

    Toggle Auto Reload

  15. Nelle opzioni di formattazione dell'oggetto visivo espandere Circle.

    Circle format

    Modificare le opzioni Colore e Spessore.

    Per l'opzione Spessore impostare un valore minore di zero e maggiore di 10. Si noti quindi che l'oggetto visivo aggiorna il valore su un valore minimo o massimo tollerabile.

Creazione del pacchetto per l'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 Power BI report o servizi da usare e godere da altri utenti.

In questa sezione si apprenderà come

Modificare i valori delle proprietà dell'oggetto visivo

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

  2. Aprire il pbiviz.json file in Visual Studio Code.

  3. Nell'oggetto visual modificare la proprietà displayName e impostarla su Circle Card.

    Nel riquadro Visualizzazioni il nome visualizzato viene mostrato al passaggio del mouse sull'icona.

    Display Name visual

  4. Per la proprietà description immettere il testo seguente.

    Displays a formatted measure value inside a circle (Visualizza un valore di misura formattato all'interno di un cerchio)

  5. Compilare supportUrl e gitHubUrl per l'oggetto visivo.

    Esempio:

    {
        "supportUrl": "https://community.powerbi.com",
        "gitHubUrl": "https://github.com/microsoft/PowerBI-visuals-circlecard"
    }
    
  6. Immettere i dettagli personali nell'oggetto author.

  7. Salvare il file.pbiviz.json

Aggiornare l'icona

  1. Nell'oggetto assets del pbiviz.json file notare che il documento definisce un percorso di un'icona. L'icona è l'immagine visualizzata nel riquadro Visualizzazioni. Deve essere un file PNG con dimensioni di 20 pixel per 20 pixel.

  2. In Windows Explorer copiare il icon.png file e incollarlo per sostituire il file predefinito che si trova nella cartella assets.

  3. In Visual Studio Code, nel riquadro Esplora risorse espandere la cartella assets e quindi selezionare il file icon.png.

  4. Esaminare l'icona.

    Viz pane image

Creare il pacchetto dell'oggetto visivo

  1. In Visual Studio Code assicurarsi che tutti i file vengano salvati.

  2. Per creare un pacchetto dell'oggetto visivo personalizzato, in PowerShell immettere il comando seguente.

    pbiviz package
    

Questo comando crea un file pbiviz nella directory dist/ del progetto visivo e sovrascrive qualsiasi file pbiviz precedente che potrebbe esistere.

Dist folder

Il pacchetto contiene tutto il necessario per importare l'oggetto visivo personalizzato nel servizio Power BI o in un report di Power BI Desktop. È stato creato il pacchetto dell'oggetto visivo personalizzato ed è pronto per l'uso.

Importazione dell'oggetto visivo personalizzato

A questo momento è possibile importare l'oggetto visivo Circle Card in modo da poterlo usare nei report Power BI. Seguire le istruzioni riportate in Importare un file visivo dal computer locale in Power-BI per importare il circleCard.pbiviz file dalla cartella dist nel riquadro di visualizzazione Power BI.

Debug

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

Passaggi successivi