Esercitazione: Sviluppare un oggetto visivo circle card di Power BI

Gli sviluppatori possono creare oggetti visivi di Power BI personalizzati. Questi oggetti visivi possono essere usati dall'utente, dall'organizzazione o da terze parti.

In questa esercitazione si svilupperà un oggetto visivo di Power BI chiamato circle card che visualizza un valore di misura formattato all'interno di un cerchio. L'oggetto visivo circle card supporta la personalizzazione del colore di riempimento e dello spessore del contorno.

In questa esercitazione verranno illustrate le procedure per:

  • Creare un progetto di sviluppo per l'oggetto visivo.
  • Sviluppare l'oggetto visivo con elementi visivi D3.
  • Configurare l'oggetto visivo per l'elaborazione dei dati.
  • Configurare l'oggetto visivo per adattarsi alle modifiche delle dimensioni.
  • Configurare le impostazioni di colore e bordo adattive per l'oggetto visivo.

Nota

Per il codice sorgente completo di questo oggetto visivo, vedere l'oggetto visivo di Power BI della scheda circolare.

Prerequisiti

Prima di iniziare a sviluppare l'oggetto visivo di Power BI, verificare di avere tutti gli elementi elencati in questa sezione.

Creare un progetto di sviluppo

In questa sezione verrà creato un progetto per l'oggetto visivo circle card.

  1. Aprire PowerShell e passare alla cartella in cui si vuole creare il progetto.

  2. Immettere il comando seguente:

    pbiviz new CircleCard
    
  3. Passare alla cartella del progetto.

    cd CircleCard
    
  4. Avviare l'oggetto visivo circle card. L'oggetto visivo è ora in esecuzione mentre è ospitato nel computer in uso.

    pbiviz start
    

    Importante

    Non chiudere la finestra di PowerShell fino alla fine dell'esercitazione. Per arrestare l'esecuzione dell'oggetto visivo, immettere CTRL+C e se richiesto di terminare il processo batch, immettere Y e premere INVIO.

Visualizzare l'oggetto visivo nel servizio Power BI

Per testare l'oggetto visivo nel servizio Power BI, verrà usato il report us Sales Analysis . È possibile scaricare il report e caricarlo nel servizio Power BI.

È anche possibile usare il report personalizzato per testare l'oggetto visivo.

  1. Accedere a PowerBI.com e aprire il report US Sales Analysis.

  2. Selezionare Altre opzioni>Modifica.

    Screenshot of the edit option in Power B I service.

  3. Creare una nuova pagina per il test facendo clic sul pulsante Nuova pagina nella parte inferiore dell'interfaccia del servizio Power BI.

    Screenshot of the new page button in Power B I service.

  4. Dal riquadro Visualizzazioni selezionare Oggetto visivo della modalità sviluppatore.

    Screenshot of the developer visual in the visualizations pane.

    Questo oggetto visivo rappresenta l'oggetto visivo personalizzato in esecuzione nel computer. È disponibile solo quando è abilitata l'impostazione di debug di oggetti visivi personalizzati.

  5. Verificare che sia stato aggiunto un oggetto visivo all'area di disegno del report.

    Screenshot of the new visual added to the report.

    Si tratta di un oggetto visivo semplice che visualizza il numero di volte in cui è stato chiamato il metodo update. In questa fase, l'oggetto visivo non recupera i dati.

    Nota

    Se l'oggetto visivo visualizza un messaggio di errore di connessione, aprire una nuova scheda nel browser, passare a https://localhost:8080/assets/status e autorizzare il browser a usare questo indirizzo.

    Screenshot of the new visual displaying a connection error.

  6. Con il nuovo oggetto visivo selezionato, passare al riquadro Campi, espandere Sales e selezionare Quantity.

    Screenshot of the Power B I service quantity field in the sales table in the U S sales analysis report.

  7. Per testare il modo in cui l'oggetto visivo risponde, ridimensionarlo e notare che il valore Update count viene incrementato ogni volta che si ridimensiona l'oggetto visivo.

    Screenshot of the new visual displaying a different update count number, after being resized.

Aggiungere elementi visivi e testo

In questa sezione si apprenderà come trasformare l'oggetto visivo in un cerchio e fare in modo che visualizzi un testo.

Nota

In questa esercitazione viene usato Visual Studio Code (VS Code) per lo sviluppo dell'oggetto visivo di Power BI.

Modificare il file degli oggetti visivi

Configurare il file visual.ts eliminando e aggiungendo alcune righe di codice.

  1. Aprire il progetto in VS Code (File>Apri cartella).

  2. Nel riquadro Esplora espandere la cartella src e selezionare il file visual.ts.

    Screenshot of accessing the visual.ts file in V S code.

    Importante

    Notare i commenti nella parte superiore del file visual.ts. L'autorizzazione a usare i pacchetti di oggetti visivi di Power BI viene concessa gratuitamente in base alle condizioni della licenza MIT (Massachusetts Institute of Technology). Come parte del contratto, è necessario lasciare i commenti nella parte superiore del file.

  3. Rimuovere le righe di codice seguenti dal file visual.ts.

    • L'importazione di VisualSettings:

      import { VisualSettings } from "./settings";
      
    • Le quattro dichiarazioni di variabili private a livello di classe.

    • Tutte le righe di codice all'interno di constructor.

    • Tutte le righe di codice all'interno del metodo update.

    • Tutte le righe di codice rimanenti sotto il metodo update, inclusi i metodi parseSettings e enumerateObjectInstances.

  4. Aggiungere le righe di codice seguenti alla fine della sezione import:

    • IVisualHost : raccolta di proprietà e servizi usati per interagire con l'host visivo (Power BI).

      import IVisualHost = powerbi.extensibility.IVisualHost;
      
    • Libreria D3

      import * as d3 from "d3";
      type Selection<T extends d3.BaseType> = d3.Selection<T, any,any, any>;
      

      Nota

      Se la libreria non è stata installata durante l'installazione, installare la libreria JavaScript D3.

  5. Sotto la dichiarazione della classe Visual inserire le proprietà a livello di classe seguenti. È sufficiente aggiungere le righe di codice che iniziano con private.

    export class Visual implements IVisual {
        // ...
        private host: IVisualHost;
        private svg: Selection<SVGElement>;
        private container: Selection<SVGElement>;
        private circle: Selection<SVGElement>;
        private textValue: Selection<SVGElement>;
        private textLabel: Selection<SVGElement>;
        // ...
    }
    
  6. Salvare il file visual.ts.

Aggiungere un cerchio e gli elementi di testo

Aggiungere SVG (Scalable Vector Graphics) D3. In questo modo è possibile creare tre forme: un cerchio e due elementi di testo.

  1. Aprire visual.ts in VS Code.

  2. Aggiungere il codice seguente al costruttore.

    this.svg = d3.select(options.element)
        .append('svg')
        .classed('circleCard', true);
    this.container = this.svg.append("g")
        .classed('container', true);
    this.circle = this.container.append("circle")
        .classed('circle', true);
    this.textValue = this.container.append("text")
        .classed("textValue", true);
    this.textLabel = this.container.append("text")
        .classed("textLabel", true);
    

    Suggerimento

    Per migliorare la leggibilità, è consigliabile formattare il documento ogni volta che si copiano frammenti di codice nel progetto. Fare clic con il pulsante destro del mouse in un punto qualsiasi in VS Code e selezionare Formatta documento (ALT+MAIUSC+F).

  3. Salvare il file visual.ts.

Impostare la larghezza e l'altezza

Impostare la larghezza e l'altezza dell'oggetto visivo, quindi inizializzare gli attributi e gli stili degli elementi visivi.

  1. Aprire visual.ts in VS Code.

  2. Aggiungere il codice seguente nel metodo update.

    let width: number = options.viewport.width;
    let height: number = options.viewport.height;
    this.svg.attr("width", width);
    this.svg.attr("height", height);
    let radius: number = Math.min(width, height) / 2.2;
    this.circle
        .style("fill", "white")
        .style("fill-opacity", 0.5)
        .style("stroke", "black")
        .style("stroke-width", 2)
        .attr("r", radius)
        .attr("cx", width / 2)
        .attr("cy", height / 2);
    let fontSizeValue: number = Math.min(width, height) / 5;
    this.textValue
        .text("Value")
        .attr("x", "50%")
        .attr("y", "50%")
        .attr("dy", "0.35em")
        .attr("text-anchor", "middle")
        .style("font-size", fontSizeValue + "px");
    let fontSizeLabel: number = fontSizeValue / 4;
    this.textLabel
        .text("Label")
        .attr("x", "50%")
        .attr("y", height / 2)
        .attr("dy", fontSizeValue / 1.2)
        .attr("text-anchor", "middle")
        .style("font-size", fontSizeLabel + "px");
    
  3. Salvare il file visual.ts.

(Facoltativo) Esaminare il codice nel file degli oggetti visivi

Verificare che il codice nel file visuals.ts sia il seguente:

/*
*  Power BI Visual CLI
*
*  Copyright (c) Microsoft Corporation
*  All rights reserved.
*  MIT License
*
*  Permission is hereby granted, free of charge, to any person obtaining a copy
*  of this software and associated documentation files (the ""Software""), to deal
*  in the Software without restriction, including without limitation the rights
*  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
*  copies of the Software, and to permit persons to whom the Software is
*  furnished to do so, subject to the following conditions:
*
*  The above copyright notice and this permission notice shall be included in
*  all copies or substantial portions of the Software.
*
*  THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
*  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
*  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
*  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
*  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
*  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
*  THE SOFTWARE.
*/
"use strict";

import "core-js/stable";
import "./../style/visual.less";
import powerbi from "powerbi-visuals-api";
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;
import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
import VisualObjectInstance = powerbi.VisualObjectInstance;
import DataView = powerbi.DataView;
import VisualObjectInstanceEnumerationObject = powerbi.VisualObjectInstanceEnumerationObject;
import IVisualHost = powerbi.extensibility.IVisualHost;
import * as d3 from "d3";
type Selection<T extends d3.BaseType> = d3.Selection<T, any, any, any>;

export class Visual implements IVisual {
    private host: IVisualHost;
    private svg: Selection<SVGElement>;
    private container: Selection<SVGElement>;
    private circle: Selection<SVGElement>;
    private textValue: Selection<SVGElement>;
    private textLabel: Selection<SVGElement>;

    constructor(options: VisualConstructorOptions) {
        this.svg = d3.select(options.element)
            .append('svg')
            .classed('circleCard', true);
        this.container = this.svg.append("g")
            .classed('container', true);
        this.circle = this.container.append("circle")
            .classed('circle', true);
        this.textValue = this.container.append("text")
            .classed("textValue", true);
        this.textLabel = this.container.append("text")
            .classed("textLabel", true);
    }

    public update(options: VisualUpdateOptions) {
        let width: number = options.viewport.width;
        let height: number = options.viewport.height;
        this.svg.attr("width", width);
        this.svg.attr("height", height);
        let radius: number = Math.min(width, height) / 2.2;
        this.circle
            .style("fill", "white")
            .style("fill-opacity", 0.5)
            .style("stroke", "black")
            .style("stroke-width", 2)
            .attr("r", radius)
            .attr("cx", width / 2)
            .attr("cy", height / 2);
        let fontSizeValue: number = Math.min(width, height) / 5;
        this.textValue
            .text("Value")
            .attr("x", "50%")
            .attr("y", "50%")
            .attr("dy", "0.35em")
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeValue + "px");
        let fontSizeLabel: number = fontSizeValue / 4;
        this.textLabel
            .text("Label")
            .attr("x", "50%")
            .attr("y", height / 2)
            .attr("dy", fontSizeValue / 1.2)
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeLabel + "px");
    }
}

Modificare il file delle funzionalità

Eliminare le righe di codice non necessarie dal file delle funzionalità.

  1. Aprire il progetto in VS Code (File>Apri cartella).

  2. Selezionare il file capabilities.json.

    Screenshot of accessing the capabilities.json file in V S code.

  3. Rimuovere tutti gli elementi Objects (righe 14-60).

  4. Salvare il file capabilities.json.

Riavviare l'oggetto visivo circle card

Arrestare l'esecuzione dell'oggetto visivo e riavviarlo.

  1. Nella finestra di PowerShell che esegue l'oggetto visivo immettere CTRL+C e, se viene richiesto di terminare il processo batch, immettere Y e premere INVIO.

  2. In PowerShell avviare l'oggetto visivo.

    pbiviz start
    

Testare l'oggetto visivo con gli elementi aggiunti

Verificare che l'oggetto visivo visualizzi gli elementi appena aggiunti.

  1. Nel servizio Power BI aprire il report Power BI US Sales Analysis. Se si usa un report diverso per sviluppare l'oggetto visivo circle card, passare al report.

  2. Assicurarsi che l'oggetto visivo abbia la forma di un cerchio.

    Screenshot of the circle card visual shaped as a circle.

    Nota

    Se l'oggetto visivo non visualizza alcun elemento, dal riquadro Campi trascinare il campo Quantity nell'oggetto visivo per sviluppatori.

  3. Ridimensionare l'oggetto visivo.

    Si noti che il cerchio e il testo vengono ridimensionati per adattarsi alle dimensioni dell'oggetto visivo. Il metodo update viene chiamato quando si ridimensiona l'oggetto visivo e di conseguenza gli elementi visivi vengono ridimensionati.

Abilitare il ricaricamento automatico

Usare questa impostazione per assicurarsi che l'oggetto visivo venga ricaricato automaticamente ogni volta che vengono salvate le modifiche al progetto.

  1. Passare al report Power BI US Sales Analysis o al progetto con l'oggetto visivo circle card.

  2. Selezionare l'oggetto visivo circle card.

  3. Nella barra degli strumenti mobile selezionare Attiva/Disattiva ricaricamento automatico.

    Screenshot of clicking the toggle auto reload option, in the circle card visual floating toolbar.

Ottenere l'oggetto visivo per elaborare i dati

In questa sezione vengono definiti i ruoli dati e i mapping delle viste dati. Si modifica anche l'oggetto visivo per visualizzare il nome del valore visualizzato.

Configurare il file delle funzionalità

Modificare il file capabilities.json per definire il ruolo dati e i mapping di vista dati.

  • Definizione del ruolo dati

    Definire la matrice dataRoles con un ruolo dati singolo di tipo misura. Questo ruolo dati è chiamato Misura e viene visualizzato come Misura. Consente il passaggio di un campo di misura o di un campo riepilogato.

    1. Aprire il file capabilities.json in VS Code.

    2. Rimuovere tutto il contenuto all'interno della matrice dataRoles (righe 3-12).

    3. Inserire il codice seguente nella matrice dataRoles.

      {
          "displayName": "Measure",
          "name": "measure",
          "kind": "Measure"
      }
      
    4. Salvare il file capabilities.json.

  • Definizione del mapping della vista dati

    Definire un campo denominato measure nella matrice dataViewMappings . Questo campo può essere passato al ruolo dati.

    1. Aprire il file capabilities.json in VS Code.

    2. Rimuovere tutto il contenuto all'interno della matrice dataViewMappings (righe 10-30).

    3. Inserire il codice seguente nella matrice dataViewMappings.

      {
          "conditions": [
              { "measure": { "max": 1 } }
          ],
          "single": {
              "role": "measure"
          }
      }
      
    4. Salvare il file capabilities.json.

(Facoltativo) Esaminare le modifiche del codice del file di funzionalità

Verificare che l'oggetto visivo circle card visualizzi il campo Misura e controllare le modifiche apportate usando l'opzione Mostra vista dati.

  1. Nel servizio Power BI aprire il report Power BI US Sales Analysis. Se si usa un report diverso per sviluppare l'oggetto visivo circle card, passare al report.

  2. Si noti che l'oggetto visivo circle card può ora essere configurato con un campo denominato Misura. È possibile trascinare gli elementi dal riquadro Campi nel campo Misura.

    Screenshot of the circle card measure filed, in the Power BI service visualization pane.

    Nota

    Il progetto dell'oggetto visivo non include ancora logica di associazione dati.

  3. Nella barra degli strumenti mobile selezionare Mostra vista dati.

    Screenshot of the show dataview button, located in the circle card floating toolbar.

  4. Selezionare i tre puntini di sospensione per espandere la visualizzazione e selezionare Singolo per visualizzare il valore.

    Screenshot of the value figure as it's displayed in the circle card show dataview option.

  5. Espandere metadata, quindi la matrice columns ed esaminare i valori format e displayName.

    Screenshot of the format and display name values as displayed in the circle card show dataview option.

  6. Per attivare nuovamente l'oggetto visivo, sulla barra degli strumenti mobile sopra l'oggetto visivo selezionare Mostra vista dati.

Configurare l'oggetto visivo per l'utilizzo dei dati

Apportare modifiche al file visual.ts, in modo che l'oggetto visivo circle card possa usare i dati.

  1. Aprire il file visual.ts in VS Code.

  2. Assicurarsi che la riga seguente venga visualizzata nel file per importare l'interfaccia DataView dal powerbi modulo. Se non è presente nel file, aggiungerlo.

    import DataView = powerbi.DataView;
    
  3. Nel metodo update eseguire le operazioni seguenti:

    • Aggiungere l'istruzione seguente come prima istruzione. Questa istruzione assegna dataView a una variabile per semplificare l'accesso e dichiara la variabile in modo che faccia riferimento all'oggetto dataView.

      let dataView: DataView = options.dataViews[0];
      
    • Sostituire .text("Value") con questa riga di codice:

      .text(<string>dataView.single.value)
      
    • Sostituire .text("Label") con questa riga di codice:

      .text(dataView.metadata.columns[0].displayName)
      
  4. Salvare il file visual.ts.

  5. Esaminare l'oggetto visivo nel servizio Power BI.

L'oggetto visivo visualizza ora il nome e il valore del campo dati selezionato.

È stato creato un oggetto visivo di Power BI funzionante. È possibile aggiungere opzioni di formattazione oppure crearne il pacchetto così come è per l'uso immediato.

Passaggi successivi