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.
Un account Power BI Pro o Premium per utente (PPU). Se non si ha una sottoscrizione, iscriversi per una versione di prova gratuita.
Visual Studio Code (VS Code). VS Code è un ambiente di sviluppo integrato (IDE) ottimale per lo sviluppo di applicazioni JavaScript e TypeScript.
Windows PowerShell versione 4 o versione successiva (per Windows). Oppure Terminale (per OSX).
Un ambiente per lo sviluppo di un oggetto visivo di Power BI. Configurare l'ambiente per lo sviluppo di un oggetto visivo di Power BI.
Questa esercitazione usa il report US Sales Analysis. È possibile scaricare questo report e caricarlo nel servizio Power BI oppure usare il proprio report. Per altre informazioni sul servizio Power BI e sul caricamento di file, vedere l'esercitazione Introduzione alle funzionalità di creazione nel servizio Power BI.
Creare un progetto di sviluppo
In questa sezione verrà creato un progetto per l'oggetto visivo circle card.
Aprire PowerShell e passare alla cartella in cui si vuole creare il progetto.
Immettere il comando seguente:
pbiviz new CircleCardPassare alla cartella del progetto.
cd CircleCardAvviare l'oggetto visivo circle card. L'oggetto visivo è ora in esecuzione mentre è ospitato nel computer in uso.
pbiviz startImportante
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.
Nota
Prima di continuare, verificare di aver abilitato le impostazioni della modalità sviluppatore degli oggetti visivi.
Accedere a PowerBI.com e aprire il report US Sales Analysis.
Selezionare Altre opzioni>Modifica.
Creare una nuova pagina per il test facendo clic sul pulsante Nuova pagina nella parte inferiore dell'interfaccia del servizio Power BI.
Dal riquadro Visualizzazioni selezionare Oggetto visivo della modalità sviluppatore.
Questo oggetto visivo rappresenta l'oggetto visivo personalizzato in esecuzione nel computer. È disponibile solo quando è abilitata l'impostazione di debug di oggetti visivi personalizzati.
Verificare che sia stato aggiunto un oggetto visivo all'area di disegno del 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/statuse autorizzare il browser a usare questo indirizzo.
Con il nuovo oggetto visivo selezionato, passare al riquadro Campi, espandere Sales e selezionare Quantity.
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.
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.
Aprire il progetto in VS Code (File>Apri cartella).
Nel riquadro Esplora espandere la cartella src e selezionare il file visual.ts.
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.
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.
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.
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>; // ... }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.
Aprire visual.ts in VS Code.
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).
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.
Aprire visual.ts in VS Code.
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");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à.
Aprire il progetto in VS Code (File>Apri cartella).
Selezionare il file capabilities.json.
Rimuovere tutti gli elementi Objects (righe 14-60).
Salvare il file capabilities.json.
Riavviare l'oggetto visivo circle card
Arrestare l'esecuzione dell'oggetto visivo e riavviarlo.
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.
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.
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.
Assicurarsi che l'oggetto visivo abbia la forma di un cerchio.
Nota
Se l'oggetto visivo non visualizza alcun elemento, dal riquadro Campi trascinare il campo Quantity nell'oggetto visivo per sviluppatori.
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.
Passare al report Power BI US Sales Analysis o al progetto con l'oggetto visivo circle card.
Selezionare l'oggetto visivo circle card.
Nella barra degli strumenti mobile selezionare Attiva/Disattiva ricaricamento automatico.
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.
Aprire il file capabilities.json in VS Code.
Rimuovere tutto il contenuto all'interno della matrice dataRoles (righe 3-12).
Inserire il codice seguente nella matrice dataRoles.
{ "displayName": "Measure", "name": "measure", "kind": "Measure" }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.
Aprire il file capabilities.json in VS Code.
Rimuovere tutto il contenuto all'interno della matrice dataViewMappings (righe 10-30).
Inserire il codice seguente nella matrice dataViewMappings.
{ "conditions": [ { "measure": { "max": 1 } } ], "single": { "role": "measure" } }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.
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.
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.
Nota
Il progetto dell'oggetto visivo non include ancora logica di associazione dati.
Nella barra degli strumenti mobile selezionare Mostra vista dati.
Selezionare i tre puntini di sospensione per espandere la visualizzazione e selezionare Singolo per visualizzare il valore.
Espandere metadata, quindi la matrice columns ed esaminare i valori format e displayName.
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.
Aprire il file visual.ts in VS Code.
Assicurarsi che la riga seguente venga visualizzata nel file per importare l'interfaccia
DataViewdalpowerbimodulo. Se non è presente nel file, aggiungerlo.import DataView = powerbi.DataView;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)
Salvare il file visual.ts.
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.