Självstudie: Skapa ett visuellt Power BI-objekt med React

Som utvecklare kan du skapa egna visuella Power BI-objekt. Dessa visuella objekt kan användas av dig, din organisation eller av tredje part.

I den här självstudien utvecklar du ett visuellt Power BI-objekt med React. Det visuella objektet visar ett formaterat måttvärde i en cirkel. Det visuella objektet har anpassningsbar storlek och gör att du kan anpassa dess inställningar.

I den här självstudien lär du dig att:

  • Skapa ett utvecklingsprojekt för ditt visuella objekt.
  • Utveckla ditt visuella objekt med React.
  • Konfigurera ditt visuella objekt för att bearbeta data.
  • Konfigurera ditt visuella objekt så att det anpassas efter storleksändringar.
  • Konfigurera anpassningsbara färg- och kantlinjeinställningar för ditt visuella objekt.

Kommentar

Den fullständiga källkoden för det här visuella objektet finns i React-cirkelkortets visuella Power BI-objekt.

Förutsättningar

Innan du börjar utveckla ditt visuella Power BI-objekt kontrollerar du att allt visas i det här avsnittet.

Skapa ett utvecklingsprojekt

I det här avsnittet skapar du ett projekt för det visuella react-cirkelkortet.

  1. Öppna PowerShell och navigera till mappen som du vill skapa projektet i.

  2. Ange följande kommando:

    pbiviz new ReactCircleCard

  3. Gå till projektets mapp.

    cd ReactCircleCard

  4. Starta det visuella objektet React-cirkelkortet. Det visuella objektet körs nu när det finns på datorn.

    pbiviz start

    Viktigt!

    Om du vill hindra det visuella objektet från att köras anger du Ctrl+C i PowerShell och om du uppmanas att avsluta batchjobbet anger du Y och trycker på Retur.

Visa React-cirkelkortet i Power BI-tjänst

För att testa det visuella objektet i Power BI-tjänst använder vi rapporten för försäljningsanalys i USA. Du kan ladda ned den här rapporten och ladda upp den till Power BI-tjänst.

Du kan också använda din egen rapport för att testa det visuella objektet.

Kommentar

Innan du fortsätter kontrollerar du att du har aktiverat utvecklarläget för visuella objekt.

  1. Logga in på PowerBI.com och öppna rapporten för försäljningsanalys i USA.

  2. Välj Redigera.

    Skärmbild av redigeringsalternativet i Power BI-tjänst.

  3. Skapa en ny sida för testning genom att klicka på knappen Ny sida längst ned i Power BI-tjänst-gränssnittet.

    Skärmbild av knappen ny sida i Power BI-tjänst.

  4. I fönstret Visualiseringar väljer du Det visuella objektet Utvecklare.

    Skärmbild av det visuella utvecklarobjektet i visualiseringsfönstret.

    Det här visuella objektet representerar det anpassade visuella objekt som du kör på datorn. Den är bara tillgänglig när inställningen för felsökning av anpassade visuella objekt är aktiverad.

  5. Kontrollera att ett visuellt objekt har lagts till på rapportarbetsytan.

    Skärmbild av det nya visuella objektet som lagts till i rapporten.

    Det här är ett enkelt visuellt objekt som visar hur många gånger uppdateringsmetoden har anropats. I det här skedet hämtar det visuella objektet inga data.

    Kommentar

    Om det visuella objektet visar ett felmeddelande om anslutning öppnar du en ny flik i webbläsaren, navigerar till https://localhost:8080/assetsoch ger webbläsaren behörighet att använda den här adressen.

    Skärmbild av det nya visuella objektet som visar ett anslutningsfel.

  6. Medan det nya visuella objektet är markerat går du till fönstret Data , expanderar Försäljning och väljer Kvantitet.

    Skärmbild av fältet Power BI-tjänst kvantitet i försäljningstabellen i rapporten för försäljningsanalys i USA.

  7. Om du vill testa hur det visuella objektet svarar ändrar du storlek på det och märker att värdet för antal uppdateringar ökar varje gång du ändrar storlek på det visuella objektet.

    Skärmbild av det nya visuella objektet som visar ett annat antal uppdateringar när det har storleksändrats.

Konfigurera React i projektet

I det här avsnittet får du lära dig hur du konfigurerar React för ditt visuella Power BI-projekt.

Öppna PowerShell och stoppa det visuella objektet från att köras genom att ange Ctrl+C. Om du uppmanas att avsluta batchjobbet anger du Y och trycker på Retur.

Installera React

Om du vill installera nödvändiga React-beroenden öppnar du PowerShell i mappen ReactCircleCard och kör följande kommando:

npm i react react-dom

Installera React-typdefinitioner

Om du vill installera typdefinitioner för React öppnar du PowerShell i mappen reactCircleCard och kör följande kommando:

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

Skapa en React-komponentklass

Följ de här stegen för att skapa en React-komponentklass.

  1. Öppna VS Code och gå till mappen reactCircleCard .

  2. Skapa en ny fil genom att välja Ny fil>.

  3. Kopiera följande kod till den nya filen.

    import * as React from "react";

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

export default ReactCircleCard;

  4. Välj Spara som och gå till mappen src .

  5. Spara filen på följande sätt:

    • I fältet Filnamn anger du komponenten.
    • I den nedrullningsbara menyn Spara som-typ väljer du TypeScript React.

Lägg till React i den visuella filen

Ersätt koden i filen visual.ts med kod som möjliggör användning av React.

  1. I mappen src öppnar du visual.ts och ersätter koden i filen med följande kod:

    "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) {

    }
}

    Kommentar

    Eftersom standardinställningarna för Power BI TypeScript inte känner igen React tsx-filer markeras component VS Code som ett fel.

  2. Om du vill återge komponenten lägger du till HTML-målelementet i visual.ts. Det här elementet finns HTMLElement i VisualConstructorOptions, som skickas till konstruktorn.

    1. Öppna visual.ts i mappen src.

    2. Lägg till följande kod i Visual klassen:

    private target: HTMLElement;
private reactRoot: React.ComponentElement<any, any>;
    1. Lägg till följande rader i VisualConstructorOptions konstruktorn:
    this.reactRoot = React.createElement(ReactCircleCard, {});
this.target = options.element;

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

    Din visual.ts fil bör nu se ut så här:

    "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. Spara visual.ts.

Redigera tsconfig-filen

Redigera tsconfig.json för att arbeta med React.

  1. I mappen reactCircleCard öppnar du tsconfig.json och lägger till två rader i compilerOptions början av objektet.

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

    Din tsconfig.json fil bör nu se ut så här, och component felet i visual.ts bör vara borta.

    {
    "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. Spara tsconfig.json.

Testa ditt visuella objekt

Öppna PowerShell i mappen CircleCardVisual och kör projektet:

pbiviz start

När du lägger till ett nytt visuellt utvecklarobjekt i rapporten i Power BI-tjänst ser det ut så här:

Skärmbild som visar meddelandet hello React i det nyligen skapade visuella utvecklarobjektet i Power BI-tjänsten.

Konfigurera det visuella objektets datafält

Konfigurera det visuella objektets funktionsfil så att endast ett datafält kan skickas till det visuella objektets måttdatafält .

  1. Öppna capabilities.json från mappen reactCircleCard i VS Code.

  2. ReactCircleCard Visar ett enda värde, Measure Data. Ta bort objektet Category Data från dataRoles.

    När du Category Data har tagit bort objektet dataRoles ser nyckeln ut så här:

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

  3. Ta bort allt innehåll i objects nyckeln (du fyller i den senare).

    När du tar bort innehållet objects ser nyckeln ut så här:

    "objects": {},

  4. Ersätt egenskapen dataViewMappings med följande kod. max: 1 i measure anger att endast ett datafält kan skickas till det visuella objektets måttdatafält .

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

  5. Spara de ändringar som du har gjort i capabilities.json.

  6. Kontrollera att pbiviz start körs och uppdatera det visuella objektet React Circle Card i Power BI-tjänst. Fältet Måttdata kan bara acceptera ett datafält, enligt vad som anges av max: 1.

    Skärmbild som visar fältet Data i react-cirkelkortet i Power BI-tjänsten.

Uppdatera det visuella objektets formatmall

I det här avsnittet omvandlar du det visuella objektets form till en cirkel. Använd filen visual.less för att styra stilen för ditt visuella objekt.

  1. Öppna visual.less från formatmappen.

  2. Ersätt innehållet i visual.less med följande kod.

    .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. Spara visual.less.

Ange att det visuella objektet ska ta emot egenskaper från Power BI

I det här avsnittet konfigurerar du det visuella objektet så att det tar emot data från Power BI och skickar uppdateringar till instanserna i filen component.tsx .

Rendera data med React

Du kan återge data med React. Komponenten kan visa data från sitt eget tillstånd.

  1. Öppna component.tsx från mappen reactCircleCard i VS Code.

  2. Ersätt innehållet i component.tsx med följande kod.

    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. Spara component.tsx.

Ange att ditt visuella objekt ska ta emot data

Visuella objekt tar emot data som ett argument för update metoden. I det här avsnittet uppdaterar du den här metoden för att ta emot data.

Följande kod väljer textLabel och textValue från DataView, och om data finns uppdaterar du komponenttillståndet.

  1. Öppna visual.ts från mappen src i VS Code.

  2. Ersätt raden import ReactCircleCard from "./component"; med följande kod:

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

  3. Lägg till följande kod i metoden 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. Skapa en clear metod genom att lägga till följande kod under update metoden.

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

  5. Spara visual.ts

Ange att ditt visuella objekt ska skicka data

I det här avsnittet uppdaterar du det visuella objektet för att skicka uppdateringar till instanser i komponentfilen .

  1. Öppna component.tsx från mappen src i VS Code.

  2. Lägg till följande kod i ReactCircleCard klassen:

    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. Spara component.tsx.

Visa ändringarna i det visuella objektet

Testa ditt visuella React Circle Card-objekt för att visa de ändringar du har gjort.

  1. Kontrollera att pbiviz start körs och uppdatera det visuella objektet React Circle Card i Power BI-tjänst.

  2. Lägg till Försäljning i det visuella objektets måttdatafält .

Skärmbild av försäljningsvärdet som visas i det visuella objektet react circle card i Power BI-tjänst.

Gör ditt visuella objekt storleksbart

Det visuella objektet har för närvarande fast bredd och höjd. För att göra det visuella objektet storleksbart måste du definiera variabeln size i både visual.ts - och component.tsx-filerna . I det här avsnittet gör du det visuella objektet storleksbart.

När du har slutfört stegen som beskrivs i det här avsnittet motsvarar cirkeldiametern i det visuella objektet den minsta bredden eller höjdstorleken, och du kommer att kunna ändra storlek på den i Power BI-tjänst.

Konfigurera visual.ts-filen

Hämta den aktuella storleken på det visuella visningsområdet från objektet options .

  1. Öppna visual.ts från mappen src i VS Code.

  2. Infoga den här koden för att importera IViewport gränssnittet.

    import IViewport = powerbi.IViewport;

  3. Lägg till egenskapen viewport i visual klassen.

    private viewport: IViewport;

  4. update Lägg till följande kod i metoden föreReactCircleCard.update.

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

  5. update I -metoden i ReactCircleCard.updatelägger du till size.

    size,

  6. Spara visual.ts.

Konfigurera filen component.tsx

  1. Öppna component.tsx från mappen src i VS Code.

  2. Lägg till följande kod i export interface State.

    size: number

  3. Lägg till följande kod i export const initialState: State.

    size: 200

  4. render I -metoden gör du följande ändringar i koden:

    1. Lägg till size i const { textLabel, textValue, size } = this.state;. Den här deklarationen bör nu se ut så här:

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

    2. Lägg till följande kod ovan return.

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

    3. Ersätt den första returraden<div className="circleCard"> med:

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

  5. Spara component.tsx.

Konfigurera den visuella filen

  1. Öppna visual.less från formatmappen i VS Code.

  2. I .circleCardersätter width och height med min-width och min-height.

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

  3. Spara visual.less.

Gör ditt visuella Power BI-objekt anpassningsbart

I det här avsnittet lägger du till möjligheten att anpassa ditt visuella objekt så att användarna kan göra ändringar i dess färg och kanttjocklek.

Lägga till färg och tjocklek i funktionsfilen

Lägg till färg och kanttjocklek i object egenskapen i capabilities.json.

  1. Öppna capabilities.json från mappen reactCircleCard i VS Code.

  2. Lägg till följande inställningar i egenskapen objects .

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

  3. Spara capabilities.json.

Lägga till en cirkelformateringsinställningsklass i inställningsfilen

Lägg till formateringsinställningarna Circle i settings.ts. Mer information om hur du skapar formateringsmodellinställningar finns i formateringsverktyg.

  1. Öppna settings.ts från mappen src i VS Code.

  2. Ersätt koden i settings.ts med följande kod:

    "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. Spara settings.ts.

Lägga till en metod för att tillämpa visuella inställningar

Lägg till den getFormattingModel metod som används för att tillämpa visuella inställningar och nödvändiga importer till filen visual.ts .

  1. Öppna visual.ts från mappen src i VS Code.

  2. Lägg till dessa import instruktioner överst i visual.ts.

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

  3. Lägg till följande deklaration i Visual.

    private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

  4. Lägg till metoden i getFormattingModelVisual.

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

  5. Visual I klassen lägger du till följande kodrad i constructor för att initieraformattingSettingsService

        this.formattingSettingsService = new FormattingSettingsService();

  6. Visual I klassen lägger du till följande kod update för att uppdatera inställningarna för visuell formatering till de senaste formateringsegenskaperna.

    1. Lägg till den här koden i if-instruktionen efter const size = Math.min(width, height);.

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

    2. Lägg till den här koden i ReactCircleCard.update efter size:

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

  7. Spara visual.ts.

Redigera komponentfilen

Redigera komponentfilen så att den kan återge ändringarna i det visuella objektets färg och kanttjocklek.

  1. Öppna component.tsx från mappen src i VS Code.

  2. Lägg till dessa värden i State:

    background?: string,
borderWidth?: number

  3. render I -metoden ersätter du följande kodrader:

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

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

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

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

  4. Spara component.tsx.

Granska dina ändringar

Experimentera med det visuella objektets färg och kanttjocklek, som du nu kan styra.

  1. Kontrollera att pbiviz start körs och uppdatera det visuella objektet React Circle Card i Power BI-tjänst.

  2. Välj fliken Format och expandera Cirkel.

  3. Justera det visuella objektets inställningar för färg och tjocklek och granska deras effekt på det visuella objektet.

En skärmbild av det visuella objektet react circle card i Power BI-tjänsten som visar formatalternativen för färg och kantlinjetjocklek.

Relaterat innehåll

  • Last updated on