Kurz: Vytvorenie vizuálu služby Power BI pomocou knižnice React

Ako vývojár môžete vytvárať vlastné vizuály služby Power BI. Tieto vizuály môžete používať vy, vaša organizácia alebo tretie strany.

V tomto kurze vytvoríte vizuál služby Power BI pomocou knižnice React. Vizuál zobrazuje formátovanú hodnotu mierky vnútri kruhu. Vizuál má adaptívnu veľkosť a umožňuje prispôsobiť jeho nastavenia.

V tomto kurze sa naučíte:

  • Vytvorte vývojový projekt svojho vizuálu.
  • Vyvíjajte vizuál pomocou knižnice React.
  • Nakonfigurujte svoj vizuál na spracovanie údajov.
  • Nakonfigurujte vizuál tak, aby sa prispôsobil zmenám veľkosti.
  • Nakonfigurujte nastavenia adaptívnej farby a orámovania pre svoj vizuál.

Poznámka

Úplný zdrojový kód tohto vizuálu nájdete v téme Vizuál kruhovej karty react v službe Power BI.

Požiadavky

Skôr než začnete vyvíjať vizuál služby Power BI, overte, či máte všetko, čo je uvedené v tejto časti.

Vytvorenie vývojového projektu

V tejto časti vytvoríte projekt pre vizuál kruhovej karty knižnice React.

  1. Otvorte prostredie PowerShell a prejdite do priečinka, vom si chcete projekt vytvoriť.

  2. Zadajte nasledujúci príkaz:

    pbiviz new ReactCircleCard
    
  3. Prejdite do priečinka projektu.

    cd ReactCircleCard
    
  4. Spustite vizuál kruhovej karty knižnice React. Vizuál je teraz spustený a hosťovaný vo vašom počítači.

    pbiviz start
    

    Dôležité

    Ak chcete zastaviť spúšťanie vizuálu, v prostredí PowerShell zadajte kláves Ctrl+C, po zobrazení výzvy na ukončenie dávkovej úlohy stlačte kláves Y a potom enter.

Zobrazte kruhovú kartu knižnice React v služba Power BI

Na otestovanie vizuálu v služba Power BI použijeme zostavu US Sales Analysis (Analýza predaja v USA). Stiahnite si túto zostavu a nahrajte ju do služba Power BI.

Na otestovanie vizuálu môžete použiť aj vlastnú zostavu.

Poznámka

Skôr než budete pokračovať, overte, či ste povolili nastavenia pre vývojára vizuálov.

  1. Prihláste sa do PowerBI.com a otvorte zostavu US Sales Analysis (Analýza predaja v USA).

  2. Vyberte Upraviť.

    Screenshot of the edit option in Power B I service.

  3. Kliknutím na tlačidlo Nová stránka v dolnej časti rozhrania služba Power BI vytvorte novú stránku na testovanie.

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

  4. Na table Vizualizácie vyberte položku Vizuál vývojára.

    Screenshot of the developer visual in the visualizations pane.

    Tento vizuál predstavuje vlastný vizuál, ktorý ste spustili v počítači. Je k dispozícii len v prípade, že je povolené ladenie vlastných vizuálov.

  5. Overte, či sa na plátno zostavy pridal vizuál.

    Screenshot of the new visual added to the report.

    Toto je jednoduchý vizuál, ktorý zobrazuje počet volaní metódy aktualizácie. V tejto fáze vizuál nenačítava žiadne údaje.

    Poznámka

    Ak sa vo vizuáli zobrazí chybové hlásenie o pripojení, otvorte vo svojom prehliadači novú kartu, prejdite na https://localhost:8080/assetsstránku a povoľte prehliadaču používať túto adresu.

    Screenshot of the new visual displaying a connection error.

  6. Keď je vybratý nový vizuál, prejdite na tablu Polia , rozbaľte položku Predaj a vyberte položku Množstvo.

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

  7. Ak chcete otestovať, ako vizuál reaguje, zmeňte jeho veľkosť a všimnite si, že hodnota Počet aktualizácií sa pri každej veľkosti vizuálu zvýši.

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

Nastavenie knižnice React v projekte

V tejto časti sa dozviete, ako nastaviť knižnicu React pre svoj projekt vizuálu v službe Power BI.

Otvorte prostredie PowerShell a zastavte spustenie vizuálu stlačením kombinácie klávesov Ctrl + C. Ak sa zobrazí výzva na ukončenie dávkovej úlohy, zadajte Y a stlačte kláves Enter.

Inštalácia knižnice React

Ak chcete nainštalovať požadované závislosti knižnice React, otvorte prostredie PowerShell v priečinku ReactCircleCard a spustite nasledujúci príkaz:

npm i react react-dom

Inštalácia definícií typu knižnice React

Ak chcete nainštalovať definície typov pre knižnicu React, otvorte prostredie PowerShell vo svojom priečinku reactCircleCard a spustite nasledujúci príkaz:

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

Vytvorenie triedy súčastí knižnice React

Ak chcete vytvoriť triedu súčastí knižnice React, postupujte podľa týchto krokov.

  1. Otvorte nástroj VS Code a prejdite do priečinka reactCircleCard .

  2. Výberom položky Súbor>Nový súbor vytvorte nový súbor.

  3. Skopírujte do nového súboru nasledujúci kód.

    import * as React from "react";
    
    export class ReactCircleCard extends React.Component<{}>{
        render(){
            return (
                <div className="circleCard">
                    Hello, React!
                </div>
            )
        }
    }
    
    export default ReactCircleCard;
    
  4. Vyberte položku Uložiť ako a prejdite do priečinka src .

  5. Uložte súbor takto:

    • Do poľa Názov súboru zadajte komponent.
    • V rozbaľovacej ponuke Uložiť ako typ vyberte položku TypeScript React.

Pridanie knižnice React do súboru vizuálu

Nahraďte kód v súbore visual.ts kódom, ktorý umožňuje používať knižnicu React.

  1. V priečinku src otvorte visual.ts a nahraďte kód v súbore nasledujúcim kódom:

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

    Poznámka

    Keďže predvolené nastavenia Power BI TypeScript nerozpoznávajú súbory knižnice React vo formáte tsx , nástroj VS Code zvýrazní component ako chybu.

  2. Ak chcete súčasť vykresliť, pridajte cieľový prvok HTML do súboru visual.ts. Ide o prvok HTMLElement v VisualConstructorOptionsčasti , ktorý prechádza do konštruktora.

    1. V priečinku src otvorte súbor visual.ts.

    2. Do triedy pridajte Visual nasledujúci kód:

    private target: HTMLElement;
    private reactRoot: React.ComponentElement<any, any>;
    
    1. Do konštruktora pridajte VisualConstructorOptions nasledujúce riadky:
    this.reactRoot = React.createElement(ReactCircleCard, {});
    this.target = options.element;
    
    ReactDOM.render(this.reactRoot, this.target);
    

    Súbor visual.ts by mal teraz vyzerať takto:

    "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. Uložte súbor visual.ts.

Úprava súboru tsconfig

Upravte parameter tsconfig.json tak, aby fungoval s knižnicou React.

  1. V priečinku reactCircleCard otvorte súbor tsconfig.json a pridajte dva riadky na začiatok compilerOptions položky.

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

    Súbor tsconfig.json by mal teraz vyzerať takto a chyba v súbore component visual.ts by mala byť odstránená.

    {
        "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. Uložte tsconfig.json.

Otestovanie vizuálu

Otvorte prostredie PowerShell v priečinku CircleCardVisual a spustite projekt:

pbiviz start

Keď do zostavy v služba Power BI pridáte nový vizuál vývojára, bude vyzerať takto:

Screenshot showing the hello React message in the newly created developer visual in Power B I service.

Konfigurácia údajového poľa vizuálu

Nakonfigurujte súbor možností vizuálu tak, aby bolo možné odoslať do údajového poľa vizuálu Measure iba jedno údajové pole.

  1. V nástroji VS Code otvorte z priečinka reactCircleCard súbor capabilities.json.

  2. Zobrazí ReactCircleCard jednu hodnotu . Measure Data Category Data Odstráňte objekt z časti dataRoles.

    Po odstránení Category Data objektu dataRoles bude kľúč vyzerať takto:

    "dataRoles": [
        {
            "displayName": "Measure Data",
            "name": "measure",
            "kind": "Measure"
        }
    ],
    
  3. Odstráňte všetok obsah kľúča objects (vyplníte ho neskôr).

    Po odstránení jeho obsahu objects bude kľúč vyzerať takto:

    "objects": {},
    
  4. dataViewMappings Nahraďte vlastnosť nasledujúcim kódom. max: 1 in measure určuje, že do údajového poľa Mierka vizuálu možno odoslať iba jedno údajové pole.

    "dataViewMappings": [
        {
            "conditions": [
                {
                    "measure": {
                        "max": 1
                    }
                }
            ],
            "single": {
                "role": "measure"
            }
        }
    ]
    
  5. Uložte zmeny, ktoré ste vykonali v súbore capabilities.json.

  6. Overte, či pbiviz start je aplikácia spustená a v služba Power BI, obnovte vizuál Kruhová karta knižnice React. Údajové pole Mierka môže prijať iba jedno údajové pole, ako je to uvedené v .max: 1

    Screenshot showing the measure Data field in the react circle card in Power B I service.

Aktualizácia štýlu vizuálu

V tejto časti zmeníte tvar vizuálu na kruh. Štýl vizuálu môžete ovládať použitím súboru visual.less .

  1. V priečinku style otvorte súbor visual.less.

  2. Nahraďte obsah súboru visual.less nasledujúcim kódom.

    .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. Uložiť súbor visual.less.

Nastavenie vizuálu na prijímanie vlastností zo služby Power BI

V tejto časti nakonfigurujete vizuál na prijímanie údajov zo služby Power BI a odosielanie aktualizácií inštancií v súbore component.tsx .

Vykreslenie údajov pomocou knižnice React

Údaje môžete vykresliť pomocou knižnice React. Súčasť môže zobraziť údaje z vlastného stavu.

  1. V nástroji VS Code otvorte z priečinka reactCircleCard súbor component.tsx.

  2. Nahraďte obsah súboru component.tsx nasledujúcim kódom.

    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. Uložte component.tsx.

Nastavenie vizuálu na prijímanie údajov

Vizuály prijímajú údaje ako argument update metódy . V tejto časti aktualizujete túto metódu na prijímanie údajov.

Nasledujúci kód vyberie textLabel položky a textValue z DataViewčasti . Ak existujú údaje, aktualizuje stav súčasti.

  1. V nástroji VS Code otvorte z priečinkasrc súbor visual.ts.

  2. Nahraďte riadok import ReactCircleCard from "./component"; nasledujúcim kódom:

    import { ReactCircleCard, initialState } from "./component";
    
  3. Do metódy pridajte update nasledujúci kód.

    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. Vytvorte metódu clear pridaním nasledujúceho kódu pod metódu update .

    private clear() {
        ReactCircleCard.update(initialState);
    }
    
  5. Uloženie súbor visual.ts

Nastavenie vizuálu na odosielanie údajov

V tejto časti aktualizujete vizuál tak, aby odosielal aktualizácie inštancií v súbore súčasti .

  1. V nástroji VS Code otvorte z priečinka src súbor component.tsx.

  2. Do triedy pridajte ReactCircleCard nasledujúci kód:

    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. Uložte component.tsx.

Zobrazenie zmien vo vizuáli

Otestujte vizuál Circle Card knižnice React a zobrazte si vykonané zmeny.

  1. Overte, či pbiviz start je spustený, a v služba Power BI obnovte vizuál Kruhová karta knižnice React.

  2. Pridajte položku Predaj do údajového poľa Mierka vizuálu.

Screenshot of the sales value displayed in the react circle card visual in the Power BI service.

Zmena prispôsobenia vizuálu

V súčasnosti má vizuál pevnú šírku a výšku. Na zmenu veľkosť vizuálu je potrebné definovať size premennú v súboroch visual.ts aj component.tsx. V tejto časti zmeníte veľkosť vizuálu na možnosť .

Po dokončení krokov uvedených v tejto časti bude priemer kruhu vo vizuáli zodpovedať minimálnej šírke alebo veľkosti výšky a budete môcť zmeniť jeho veľkosť v služba Power BI.

Konfigurácia súboru visual.ts

Aktuálnu veľkosť zobrazenia vizuálu options získate z objektu .

  1. V nástroji VS Code otvorte z priečinkasrc súbor visual.ts.

  2. Vložte tento kód na import IViewport rozhrania.

    import IViewport = powerbi.IViewport;
    
  3. viewport Pridajte vlastnosť do visual triedy .

    private viewport: IViewport;
    
  4. V metóde update pred ReactCircleCard.updatepridajte nasledujúci kód.

    this.viewport = options.viewport;
    const { width, height } = this.viewport;
    const size = Math.min(width, height);
    
  5. V metóde update pridajte do ReactCircleCard.updatepoľa size.

    size,
    
  6. Uložte súbor visual.ts.

Konfigurácia súboru component.tsx

  1. V nástroji VS Code otvorte z priečinka src súbor component.tsx.

  2. Do časti pridajte nasledujúci kód.export interface State

    size: number
    
  3. Do časti pridajte nasledujúci kód.export const initialState: State

    size: 200
    
  4. V metóde render vykonajte nasledujúce zmeny kódu:

    1. Pridajte size do .const { textLabel, textValue, size } = this.state; Toto vyhlásenie by teraz malo vyzerať takto:

      const { textLabel, textValue, size } = this.state;
      
    2. Pridajte nasledujúci kód nad .return

      const style: React.CSSProperties = { width: size, height: size };
      
    3. Nahraďte prvý vrátený riadok <div className="circleCard"> nasledujúcim riadkom:

      <div className="circleCard" style={style}>
      
  5. Uložte component.tsx.

Konfigurácia súboru vizuálu

  1. V nástroji VS Code otvorte v priečinku style súbor visual.less.

  2. V .circleCardparametri nahraďte width reťazce a height znakmi min-width a min-height.

    min-width: 200px;
    min-height: 200px;
    
  3. Uložiť súbor visual.less.

Prispôsobenie vizuálu služby Power BI

V tejto časti pridáte možnosť prispôsobiť vizuál a umožníte používateľom vykonať zmeny v jeho farbe a hrúbke orámovania.

Pridanie farby a hrúbky do súboru možností

Pridajte hrúbku farby a orámovania do object vlastnosti capabilities.json.

  1. V nástroji VS Code otvorte z priečinka reactCircleCard súbor capabilities.json.

  2. Do vlastnosti pridajte nasledujúce nastavenia objects .

    "circle": {
        "properties": {
           "circleColor": {
                "type": {
                    "fill": {
                        "solid": {
                            "color": true
                        }
                    }
                }
            },
            "circleThickness": {
                "type": {
                    "numeric": true
                }
            }
        }
    }
    
  3. Uložte súbor capabilities.json.

Pridanie triedy nastavení formátovania kruhu do súboru nastavení

Pridajte nastavenia formátovania Circle do časti settings.ts. Ďalšie informácie o tom, ako vytvoriť nastavenia modelu formátovania, nájdete v téme Pomôcky formátovania.

  1. V nástroji VS Code otvorte v priečinkusrc súbor settings.ts.

  2. Nahraďte kód v časti settings.ts nasledujúcim kódom:

    "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. Uložte položku settings.ts.

Pridanie metódy na použitie nastavení vizuálu

Pridajte metódu použitú getFormattingModel na použitie nastavení vizuálu a požadovaných importov do súboru visual.ts .

  1. V nástroji VS Code otvorte z priečinkasrc súbor visual.ts.

  2. Pridajte tieto import príkazy na začiatok príkazu visual.ts.

    import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";
    import { VisualFormattingSettingsModel } from "./settings";
    
  3. Do vizuálu pridajte nasledujúcu deklaráciu.

    private formattingSettings: VisualFormattingSettingsModel;
    private formattingSettingsService: FormattingSettingsService;
    
  4. Pridajte metódu do vizuálu getFormattingModel.

    public getFormattingModel(): powerbi.visuals.FormattingModel {
        return this.formattingSettingsService.buildFormattingModel(this.formattingSettings);
    }
    
  5. Visual Do triedy pridajte na inicializáciu nasledujúci riadok constructor kóduformattingSettingsService

        this.formattingSettingsService = new FormattingSettingsService();
    
    
  6. Visual V triede pridajte nasledujúci kód na update aktualizáciu nastavení formátovania vizuálu na najnovšie hodnoty vlastností formátovania.

    1. Tento kód pridajte do príkazu if po const size = Math.min(width, height);.

      this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews[0]);
      const circleSettings = this.formattingSettings.circleCard;
      
    2. Tento kód pridajte do časti ReactCircleCard.update po :size

      borderWidth: circleSettings.circleThickness.value,
      background: circleSettings.circleColor.value.value,
      }
      
  7. Uložte súbor visual.ts.

Úprava súboru súčasti

Upravte súbor súčasti tak, aby mohol vykresliť zmeny v hrúbke farby a orámovania vizuálu.

  1. V nástroji VS Code otvorte z priečinka src súbor component.tsx.

  2. Pridajte tieto hodnoty do časti State:

    background?: string,
    borderWidth?: number
    
  3. V metóde nahraďte render nasledujúce riadky kódu:

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

      const { textLabel, textValue, size, background, borderWidth } = this.state;
      
    2. const style: React.CSSProperties = { width: size, height: size }; S:

      const style: React.CSSProperties = { width: size, height: size, background, borderWidth };
      
  4. Uložte component.tsx.

Skontrolujte svoje zmeny

Experimentujte s hrúbkou farby a orámovania vizuálu, ktoré teraz môžete ovládať.

  1. Overte, či pbiviz start je spustený, a v služba Power BI obnovte vizuál Kruhová karta knižnice React.

  2. Vyberte kartu Formát a rozbaľte položku Kruh.

  3. Upravte nastavenia Farba a Hrúbka vizuálu a skontrolujte ich vplyv na vizuál.

A screenshot of the react circle card visual in Power B I service, showing the color and border thickness format options.