Condividi tramite

Esercitazione: Creare un oggetto visivo di Power BI con React

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 sviluppa un oggetto visivo di Power BI usando React. L'oggetto visivo visualizza un valore di misura formattato all'interno di un cerchio. L'oggetto visivo ha dimensioni adattive e consente di personalizzarne le impostazioni.

In questa esercitazione apprenderai a:

  • Creare un progetto di sviluppo per l'oggetto visivo.
  • Sviluppare l'oggetto visivo usando React.
  • Configurare l'oggetto visivo per elaborare i dati.
  • Configurare l'oggetto visivo per adattarsi alle modifiche alle dimensioni.
  • Configurare le impostazioni del colore adattivo e del bordo per l'oggetto visivo.

Nota

Per il codice sorgente completo di questo oggetto visivo, vedere Oggetto visivo Power BI a forma di circle card React.

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 viene creato un progetto per l'oggetto visivo circle card React.

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

  2. Immettere il comando seguente:

    pbiviz new ReactCircleCard

  3. Passare alla cartella del progetto.

    cd ReactCircleCard

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

    pbiviz start

    Importante

    Per interrompere l'esecuzione dell'oggetto visivo, in PowerShell immettere CTRL+C e, se viene richiesto di terminare il processo batch, immettere Y e premere INVIO.

Visualizzare la circle card React nella servizio Power BI

Per testare l'oggetto visivo in servizio Power BI, si userà il report Us Sales Analysis. È possibile scaricare questo report e caricarlo in servizio Power BI.

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

Nota

Prima di continuare, verificare di aver abilitato la modalità sviluppatore degli oggetti visivi.

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

  2. Seleziona Modifica

    Screenshot dell'opzione di modifica in servizio Power BI.

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

    Screenshot del pulsante nuova pagina in servizio Power BI.

  4. Nel riquadro Visualizzazioni selezionare l'oggetto visivo per sviluppatori.

    Screenshot dell'oggetto visivo per sviluppatori nel riquadro visualizzazioni.

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

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

    Screenshot del nuovo oggetto visivo aggiunto al report.

    Si tratta di un oggetto visivo semplice che visualizza il numero di chiamate al metodo di aggiornamento. In questa fase, l'oggetto visivo non recupera dati.

    Nota

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

    Screenshot del nuovo oggetto visivo che mostra un errore di connessione.

  6. Mentre il nuovo oggetto visivo è selezionato, passare al riquadro Dati, espandere Vendite e selezionare Quantità.

    Screenshot del campo servizio Power BI quantità nella tabella sales del report di analisi delle vendite degli Stati Uniti.

  7. Per testare la risposta dell'oggetto visivo, ridimensionarlo e notare che il valore conteggio aggiornamenti viene incrementato ogni volta che si ridimensiona l'oggetto visivo.

    Screenshot del nuovo oggetto visivo che mostra un numero di conteggio degli aggiornamenti diverso, dopo essere stato ridimensionato.

Configurare React nel progetto

In questa sezione viene illustrato come configurare React per il progetto visivo di Power BI.

Aprire PowerShell e arrestare l'esecuzione dell'oggetto visivo immettendo CTRL+C. Se viene richiesto di terminare il processo batch, immettere Y e premere INVIO.

Installare React

Per installare le dipendenze React necessarie, aprire PowerShell nella cartella ReactCircleCard ed eseguire il comando seguente:

npm i react react-dom

Installare le definizioni dei tipi React

Per installare le definizioni dei tipi per React, aprire PowerShell nella cartella reactCircleCard ed eseguire il comando seguente:

npm i @types/react @types/react-dom

Creare una classe componente React

Seguire questa procedura per creare una classe componente React.

  1. Aprire VS Code e passare alla cartella reactCircleCard .

  2. Creare un nuovo file selezionando File>nuovo file.

  3. Copiare il codice seguente nel nuovo file.

    import * as React from "react";

export class ReactCircleCard extends React.Component<{}>{
    render(){
        return (
            <div className="circleCard">
                Hello, React!
            </div>
        )
    }
}

export default ReactCircleCard;

  4. Selezionare Salva con nome e passare alla cartella src .

  5. Salvare il file come segue:

    • Nel campo Nome file immettere componente.
    • Dal menu a discesa Salva come tipo selezionare TypeScript React.

Aggiungere React al file visivo

Sostituire il codice nel file visual.ts con il codice che abilita l'uso di React.

  1. Nella cartella src aprire visual.ts e sostituire il codice nel file con il codice seguente:

    "use strict";
import powerbi from "powerbi-visuals-api";

import DataView = powerbi.DataView;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;

// Import React dependencies and the added component
import * as React from "react";
import * as ReactDOM from "react-dom";
import ReactCircleCard from "./component";

import "./../style/visual.less";

export class Visual implements IVisual {

    constructor(options: VisualConstructorOptions) {

    }

    public update(options: VisualUpdateOptions) {

    }
}

    Nota

    Poiché le impostazioni predefinite di TypeScript di Power BI non riconoscono i file React tsx , VS Code evidenzia component come errore.

  2. Per eseguire il rendering del componente, aggiungere l'elemento HTML di destinazione a visual.ts. Questo elemento è HTMLElement in VisualConstructorOptions, che viene passato al costruttore.

    1. Nella cartella src aprire visual.ts.

    2. Aggiungere il codice seguente alla classe Visual:

    private target: HTMLElement;
private reactRoot: React.ComponentElement<any, any>;
    1. Aggiungere le righe seguenti al VisualConstructorOptions costruttore:
    this.reactRoot = React.createElement(ReactCircleCard, {});
this.target = options.element;

ReactDOM.render(this.reactRoot, this.target);

    Il file visual.ts dovrebbe essere simile al seguente:

    "use strict";
import powerbi from "powerbi-visuals-api";

import DataView = powerbi.DataView;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;
import * as React from "react";
import * as ReactDOM from "react-dom";
import ReactCircleCard from "./component";    

import "./../style/visual.less";

export class Visual implements IVisual {
    private target: HTMLElement;
    private reactRoot: React.ComponentElement<any, any>;

    constructor(options: VisualConstructorOptions) {
        this.reactRoot = React.createElement(ReactCircleCard, {});
        this.target = options.element;

        ReactDOM.render(this.reactRoot, this.target);
    }

    public update(options: VisualUpdateOptions) {

    }
}

  3. Salvare visual.ts.

Modificare il file tsconfig

Modificare il tsconfig.json per lavorare con React.

  1. Nella cartella reactCircleCard aprire tsconfig.json e aggiungere due righe all'inizio dell'elementocompilerOptions.

    "jsx": "react",
"types": ["react", "react-dom"],

    Il file tsconfig.json dovrebbe essere simile al seguente e l'errore component in visual.ts dovrebbe essere scomparso.

    {
    "compilerOptions": {
        "jsx": "react",
        "types": ["react", "react-dom"],
        "allowJs": false,
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        "target": "es6",
        "sourceMap": true,
        "outDir": "./.tmp/build/",
        "moduleResolution": "node",
        "declaration": true,
        "lib": [
            "es2015",
            "dom"
        ]
    },
    "files": [
        "./src/visual.ts"
    ]
}

  2. Salvare tsconfig.json.

Testare l'oggetto visivo

Aprire PowerShell nella cartella CircleCardVisual ed eseguire il progetto:

pbiviz start

Quando si aggiunge un nuovo oggetto visivo sviluppatore al report nel servizio Power BI, l'aspetto è simile al seguente:

Screenshot che mostra il messaggio hello React nell'oggetto visivo sviluppatore appena creato nel servizio Power BI.

Configurare il campo dati dell'oggetto visivo

Configurare il file delle funzionalità dell'oggetto visivo in modo che sia possibile inviare un solo campo dati al campo dati Measure dell'oggetto visivo.

  1. In VS Code, dalla cartella reactCircleCard , aprire capabilities.json.

  2. ReactCircleCard Visualizza un singolo valore, Measure Data. Rimuovere l'oggetto Category Data da dataRoles.

    Dopo aver rimosso l'oggetto Category Data , la dataRoles chiave sarà simile alla seguente:

    "dataRoles": [
    {
        "displayName": "Measure Data",
        "name": "measure",
        "kind": "Measure"
    }
],

  3. Rimuovere tutto il contenuto della objects chiave ,che verrà compilato in un secondo momento.

    Dopo aver rimosso il contenuto, la objects chiave sarà simile alla seguente:

    "objects": {},

  4. Sostituire la dataViewMappings proprietà con il codice seguente. max: 1in measure specifica che è possibile inviare un solo campo dati al campo dati Misura dell'oggetto visivo.

    "dataViewMappings": [
    {
        "conditions": [
            {
                "measure": {
                    "max": 1
                }
            }
        ],
        "single": {
            "role": "measure"
        }
    }
]

  5. Salvare le modifiche apportate a capabilities.json.

  6. Verificare che pbiviz start sia in esecuzione e in servizio Power BI aggiornare l'oggetto visivo React Circle Card. Il campo Dati misura può accettare un solo campo dati, come specificato da max: 1.

    Screenshot che mostra il campo dati della misura nella scheda cerchio react nel servizio Power BI.

Aggiornare lo stile dell'oggetto visivo

In questa sezione si trasforma la forma dell'oggetto visivo in un cerchio. Usare il file visual.less per controllare lo stile dell'oggetto visivo.

  1. Dalla cartella di stile aprire visual.less.

  2. Sostituire il contenuto di visual.less con il codice seguente.

    .circleCard {
    position: relative;
    box-sizing: border-box;
    border: 1px solid #000;
    border-radius: 50%;
    width: 200px;
    height: 200px;
}

p {
    text-align: center;
    line-height: 30px;
    font-size: 20px;
    font-weight: bold;

    position: relative;
    top: -30px;
    margin: 50% 0 0 0;
}

  3. Salvare visual.less.

Impostare l'oggetto visivo per ricevere le proprietà da Power BI

In questa sezione si configura l'oggetto visivo per ricevere dati da Power BI e si inviano aggiornamenti alle istanze nel file component.tsx .

Eseguire il rendering dei dati con React

È possibile eseguire il rendering dei dati usando React. Il componente può visualizzare i dati dal proprio stato.

  1. In VS Code aprire component.tsx dalla cartella reactCircleCard.

  2. Sostituire il contenuto di component.tsx con il codice seguente.

    import * as React from "react";

export interface State {
    textLabel: string,
    textValue: string
}

export const initialState: State = {
    textLabel: "",
    textValue: ""
}

export class ReactCircleCard extends React.Component<{}, State>{
    constructor(props: any){
        super(props);
        this.state = initialState;
    }

    render(){
        const { textLabel, textValue } = this.state;

        return (
            <div className="circleCard">
                <p>
                    {textLabel}
                    <br/>
                    <em>{textValue}</em>
                </p>
            </div>
        )
    }
}

  3. Salvare component.tsx.

Impostare l'oggetto visivo per ricevere i dati

Gli oggetti visivi ricevono i dati come argomento del update metodo . In questa sezione si aggiorna questo metodo per ricevere i dati.

Il codice seguente seleziona textLabel e textValue da DataViewe, se i dati esistono, aggiorna lo stato del componente.

  1. In VS Code, dalla cartella src , aprire visual.ts.

  2. Sostituire la riga import ReactCircleCard from "./component"; con il codice seguente:

    import { ReactCircleCard, initialState } from "./component";

  3. Aggiungere il codice seguente al metodo update.

    if(options.dataViews && options.dataViews[0]){
    const dataView: DataView = options.dataViews[0];

    ReactCircleCard.update({
        textLabel: dataView.metadata.columns[0].displayName,
        textValue: dataView.single.value.toString()
    });
} else {
    this.clear();
}

  4. Creare un clear metodo aggiungendo il codice seguente sotto il update metodo .

    private clear() {
    ReactCircleCard.update(initialState);
}

  5. Salva visual.ts

Impostare l'oggetto visivo per l'invio di dati

In questa sezione si aggiorna l'oggetto visivo per inviare aggiornamenti alle istanze nel file del componente .

  1. In VS Code aprire component.tsx dalla cartella src.

  2. Aggiungere il codice seguente alla classe ReactCircleCard:

    private static updateCallback: (data: object) => void = null;

public static update(newState: State) {
    if(typeof ReactCircleCard.updateCallback === 'function'){
        ReactCircleCard.updateCallback(newState);
    }
}

public state: State = initialState;

public componentWillMount() {
        ReactCircleCard.updateCallback = (newState: State): void => { this.setState(newState); };
}

public componentWillUnmount() {
    ReactCircleCard.updateCallback = null;
}

  3. Salvare component.tsx.

Visualizzare le modifiche apportate all'oggetto visivo

Testare l'oggetto visivo React Circle Card per visualizzare le modifiche apportate.

  1. Verificare che pbiviz start sia in esecuzione e nella servizio Power BI aggiornare l'oggetto visivo React Circle Card.

  2. Aggiungere Sales al campo dati Measure dell'oggetto visivo.

Screenshot del valore di vendita visualizzato nell'oggetto visivo circle card react nel servizio Power BI.

Rendere ridimensionabile l'oggetto visivo

Attualmente, l'oggetto visivo ha una larghezza e un'altezza fisse. Per rendere ridimensionabile l'oggetto visivo, è necessario definire la size variabile nei file visual.ts e component.tsx . In questa sezione si rende ridimensionabile l'oggetto visivo.

Dopo aver completato i passaggi descritti in questa sezione, il diametro del cerchio nell'oggetto visivo corrisponderà alla larghezza o all'altezza minima e sarà possibile ridimensionarlo in servizio Power BI.

Configurare il file visual.ts

Ottiene le dimensioni correnti del riquadro di visualizzazione visivo dall'oggetto options .

  1. In VS Code, dalla cartella src , aprire visual.ts.

  2. Inserire questo codice per importare l'interfaccia IViewport .

    import IViewport = powerbi.IViewport;

  3. Aggiungere la viewport proprietà alla visual classe .

    private viewport: IViewport;

  4. update Nel metodo, prima ReactCircleCard.updatedi , aggiungere il codice seguente.

    this.viewport = options.viewport;
const { width, height } = this.viewport;
const size = Math.min(width, height);

  5. update Nel metodo aggiungere ReactCircleCard.updatesizein .

    size,

  6. Salvare visual.ts.

Configurare il file component.tsx

  1. In VS Code aprire component.tsx dalla cartella src.

  2. Aggiungere il codice seguente a export interface State.

    size: number

  3. Aggiungere il codice seguente a export const initialState: State.

    size: 200

  4. render Nel metodo apportare le modifiche seguenti al codice:

    1. Aggiunta di size a const { textLabel, textValue, size } = this.state;. La dichiarazione dovrebbe ora essere simile alla seguente:

      const { textLabel, textValue, size } = this.state;

    2. Aggiungere il codice seguente sopra return.

      const style: React.CSSProperties = { width: size, height: size };

    3. Sostituire la prima con:

      <div className="circleCard" style={style}>

  5. Salvare component.tsx.

Configurare il file visivo

  1. In VS Code, dalla cartella di stile, aprire visual.less.

  2. In .circleCardsostituire width e height con min-width e min-height.

    min-width: 200px;
min-height: 200px;

  3. Salvare visual.less.

Personalizzare l'oggetto visivo di Power BI

In questa sezione si aggiunge la possibilità di personalizzare l'oggetto visivo, consentendo agli utenti di apportare modifiche al colore e allo spessore del bordo.

Aggiungere colore e spessore al file delle funzionalità

Aggiungere il colore e lo spessore del bordo alla object proprietà in capabilities.json.

  1. In VS Code, dalla cartella reactCircleCard , aprire capabilities.json.

  2. Aggiungere le impostazioni seguenti alla objects proprietà .

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

  3. Salvare capabilities.json.

Aggiungere una classe di impostazioni di formattazione cerchio al file di impostazioni

Aggiungere le Circle impostazioni di formattazione a settings.ts. Per altre informazioni su come compilare le impostazioni del modello di formattazione, vedere Formattazione delle utilità.

  1. In VS Code, dalla cartella src , aprire settings.ts.

  2. Sostituire il codice in settings.ts con il codice seguente:

    "use strict";

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCard = formattingSettings.SimpleCard;
import FormattingSettingsSlice = formattingSettings.Slice;
import FormattingSettingsModel = formattingSettings.Model;

/**
* Circle Formatting Card
*/
class CircleCardSettings extends FormattingSettingsCard {
    circleColor = new formattingSettings.ColorPicker({
        name: "circleColor", // circle color name should match circle color property name in capabilities.json
        displayName: "Color",
        description: "The fill color of the circle.",
        show: true,
        value: { value: "white" }
    });

    circleThickness = new formattingSettings.NumUpDown({
        name: "circleThickness", // circle thickness name should match circle color property name in capabilities.json
        displayName: "Thickness",
        description: "The circle thickness.",
        show: true,
        value: 2
    });

    name: string = "circle"; // circle card name should match circle object name in capabilities.json
    displayName: string = "Circle";
    show: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.circleColor, this.circleThickness];
}

/**
* visual settings model class
*
*/
export class VisualFormattingSettingsModel extends FormattingSettingsModel {
    // Create formatting settings model circle formatting card
    circleCard = new CircleCardSettings();

    cards = [this.circleCard];
}

  3. Salvare settings.ts.

Aggiungere un metodo per applicare le impostazioni visive

Aggiungere il getFormattingModel metodo usato per applicare le impostazioni visive e le importazioni necessarie al file visual.ts .

  1. In VS Code, dalla cartella src , aprire visual.ts.

  2. Aggiungere queste import istruzioni nella parte superiore di visual.ts.

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

  3. Aggiungere la dichiarazione seguente a Visual.

    private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

  4. Aggiungere il getFormattingModel metodo a Visual.

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

  5. Visual Nella classe aggiungere la riga di codice seguente a constructor per inizializzareformattingSettingsService

        this.formattingSettingsService = new FormattingSettingsService();

  6. Visual Nella classe aggiungere il codice seguente per update aggiornare le impostazioni di formattazione visiva ai valori più recenti delle proprietà di formattazione.

    1. Aggiungere questo codice all'istruzione if dopo const size = Math.min(width, height);.

      this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews[0]);
const circleSettings = this.formattingSettings.circleCard;

    2. Aggiungere questo codice a ReactCircleCard.update dopo size:

      borderWidth: circleSettings.circleThickness.value,
background: circleSettings.circleColor.value.value,
}

  7. Salvare visual.ts.

Modificare il file del componente

Modificare il file del componente in modo che possa eseguire il rendering delle modifiche apportate allo spessore del colore e del bordo dell'oggetto visivo.

  1. In VS Code aprire component.tsx dalla cartella src.

  2. Aggiungere questi valori a State:

    background?: string,
borderWidth?: number

  3. render Nel metodo sostituire le righe di codice seguenti:

    1. const { textLabel, textValue, size } = this.state; con:

      const { textLabel, textValue, size, background, borderWidth } = this.state;

    2. const style: React.CSSProperties = { width: size, height: size }; con:

      const style: React.CSSProperties = { width: size, height: size, background, borderWidth };

  4. Salvare component.tsx.

Esaminare le modifiche

Sperimentare lo spessore del colore e del bordo dell'oggetto visivo, che è ora possibile controllare.

  1. Verificare che pbiviz start sia in esecuzione e nella servizio Power BI aggiornare l'oggetto visivo React Circle Card.

  2. Selezionare la scheda Formato ed espandere Cerchio.

  3. Regolare le impostazioni Colore e Spessore dell'oggetto visivo ed esaminarne l'effetto sull'oggetto visivo.

Screenshot dell'oggetto visivo circle card react nel servizio Power BI, che mostra le opzioni di formato di spessore del colore e del bordo.

Contenuto correlato

  • Last updated on