Share via

Kurz: Vývoj vlastného kruhového vizuálu karty Power BI

  • Článok

V tomto kurze vytvoríte vizuál služby Power BI nazvaný kruhová karta, ktorý zobrazuje formátovanú hodnotu mierky v kruhu. Vizuál kruhovej karty podporuje prispôsobenie farby výplne a hrúbky obrysu.

V tomto kurze sa naučíte:

  • Vytvorte vývojový projekt svojho vizuálu.
  • Vyvinúť vizuál pomocou vizuálnych prvkov knižnice D3.
  • 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 Kruhová karta vizuálu služby 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.

Poznámka

V tomto kurze sa na vývoj vizuálu služby Power BI používa nástroj Visual Studio Code (VS Code).

  1. Otvorte nový terminál v nástroji VS Code a prejdite do priečinka, vom si chcete projekt vytvoriť.

  2. V termináli prostredia PowerShell zadajte nasledujúci príkaz:

    pbiviz new CircleCard

  3. Otvorte priečinok CircleCard v prieskumníkovi programu VS Code. (Súbor>Otvorte priečinok).

    Screenshot of VS code window opened to the circle card folder.

    Podrobné vysvetlenie funkcie každého z týchto súborov nájdete v téme Štruktúra vizuálu projektu služby Power BI.

  4. Skontrolujte okno terminálu a potvrďte, že sa nachádzate v adresári circleCard. Nainštalujte si závislosti vizuálnych nástrojov Power BI.

    npm install

    Prepitné

    Ak chcete zistiť, ktoré závislosti boli nainštalované vo vašom vizuáli , skontrolujte súbor package.json .

  5. Spustite vizuál kruhovej karty.

    pbiviz start

    Vizuál je teraz spustený a hosťovaný vo vašom počítači.

    Dôležité

    Okno prostredia PowerShell nezatvárajte až do konca kurzu. Ak chcete zastaviť spúšťanie vizuálu, stlačte kláves Ctrl+C. Ak sa zobrazí výzva na ukončenie dávkovej úlohy, zadajte hodnotu Y a potom enter.

Zobrazenie vizuálu na 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.

Pridanie prvkov a textu vizuálu

V tejto časti sa naučíte, ako zmeniť vizuál na kruh a nastaviť ho tak, aby zobrazoval text.

Úprava súboru vizuálov

Nastavte súbor visual.ts .

Prepitné

Ak chcete zlepšiť čitateľnosť, odporúča sa formátovať dokument vždy po kopírovaní úryvkov kódu do projektu. Kliknite pravým tlačidlom myši na ľubovoľné miesto v nástroji VS Code a vyberte položku Format Document (Formátovať dokument) (alebo zadajte kláves Alt+Shift+F).

  1. V nástroji VS Code na table Prieskumník rozbaľte priečinoksrc a vyberte súbor visual.ts.

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

  2. Odstráňte všetok kód v komentári k licencii MIT.

    Dôležité

    Všimnite si komentáre v hornej časti súboru visual.ts . Povolenie na používanie balíkov vizuálov služby Power BI je bezplatné a udelené na základe licencie MIT (Massachusetts Institute of Technology). Súčasťou zmluvy je, že musíte v hornej časti súboru zanechať komentáre.

  3. Importujte potrebné knižnice a moduly a definujte výber typu pre knižnicu d3:

    "use strict";

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 DataView = powerbi.DataView;
import IVisualHost = powerbi.extensibility.IVisualHost;
import * as d3 from "d3";
type Selection<T extends d3.BaseType> = d3.Selection<T, any, any, any>;

    Poznámka

    Ak knižnica JavaScript D3 nebola nainštalovaná ako súčasť vášho nastavenia, nainštalujte ju teraz. V prostredí PowerShell spustite npm i d3@latest --save

    Všimnite si, že medzi importovanými položkami sú:

    • IVisualHost – kolekcia vlastností a služieb, ktoré sa používajú na interakciu s hostiteľom vizuálu (Power BI).
    • Knižnica D3 – knižnica JavaScript na vytváranie dokumentov riadených údajmi.

  4. Pod importom vytvorte prázdnu triedu vizuálu . Trieda visual implementuje rozhranie IVisual, kde všetky vizuály začínajú:

    export class Visual implements IVisual {

}

    Informácie o tom, čo sa deje v triede vizuálu, nájdete v téme Rozhranie API vizuálu. V nasledujúcich troch krokoch zadefinujeme túto triedu.

  5. Pridajte súkromné metódy na úrovni triedy na začiatku triedy vizuálu:

    private host: IVisualHost;
private svg: Selection<SVGElement>;
private container: Selection<SVGElement>;
private circle: Selection<SVGElement>;
private textValue: Selection<SVGElement>;
private textLabel: Selection<SVGElement>;

    Všimnite si, že niektoré z týchto súkromných metód používajú typ výberu.

  6. Definujte kruhové a textové prvky v metóde konštruktora. Táto metóda sa volá pri vytváraní inštancie vizuálu. SvG (Scalable Vector Graphics) knižnice D3 umožňuje vytvárať tri tvary: kruh a dva textové prvky:

    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);
}

  7. Definujte šírku a výšku v metóde update. Táto metóda sa volá vždy, keď dôjde k zmene údajov alebo hostiteľského prostredia, ako je napríklad nová hodnota alebo zmena veľkosti.

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

  8. Uložte súbor visual.ts.

(Voliteľné) Kontrola kódu v súbore vizuálov

Skontrolujte, či konečný kód v súbore visual.ts vyzerá takto:

/*
*  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 "./../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 DataView = powerbi.DataView;
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");
    }
}

Úprava súboru možností

Vizuál kruhovej karty je jednoduchý vizuál, ktorý na table Formát nevytvorí žiadne objekty. Preto môžete časti súboru bezpečne odstrániť.

  1. Otvorte projekt v nástroji VS Code (File>Open Folder ) .

  2. Vyberte súbor capabilities.json.

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

  3. Odstráňte celé pole objektov.
    Medzi rolami dataRoles a dataViewMappings nezanechajte žiadne prázdne riadky.

  4. Uložte súbor capabilities.json.

Reštart vizuálu kruhovej karty

Zastavte spustený vizuál a reštartujte ho.

  1. V okne prostredia PowerShell, v ktorom ste spustili vizuál, zadajte kláves Ctrl+C. Ak sa zobrazí výzva na ukončenie dávkovej úlohy, zadajte hodnotu Y a potom enter.

  2. V prostredí PowerShell spustite vizuál znova.

    pbiviz start

Testovanie vizuálu s pridanými prvkami

Overte, či vizuál zobrazuje novopridané prvky.

  1. V služba Power BI otvorte zostavu Power BI US Sales Analysis (Analýza predaja v USA služby Power BI). Ak na vývoj vizuálu kruhovej karty používate inú zostavu, prejdite na túto zostavu.

  2. Presuňte hodnotu do poľa Measure (Mierka ) a uistite sa, že vizuál má tvar kruhu.

    Screenshot of the circle card visual shaped as a circle.

    Ak sa vo vizuáli nič nezobrazuje, z tably Polia presuňte pole Quantity (Množstvo ) do vizuálu vývojára.

  3. Zmeňte veľkosť vizuálu.

    Všimnite si, že veľkosť kruhu a textu sa prispôsobia rozmerom vizuálu. Pri zmene veľkosti vizuálu sa volá metóda update, v dôsledku čoho prvky vizuálu zmeňú veľkosť.

Povolenie automatického opätovného načítanie

Pomocou tohto nastavenia zaistíte, že vizuál sa automaticky znova načíta vždy, keď uložíte zmeny v projekte.

  1. Prejdite na zostavu Power BI US Sales Analysis (Analýza predaja v USA služby Power BI) (alebo na projekt, ktorý obsahuje váš vizuál kruhovej karty).

  2. Vyberte vizuál kruhovej karty.

  3. Na plávajúcom paneli s nástrojmi vyberte položku Prepnúť automatické opätovné načítanie.

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

Spracovanie údajov pomocou vizuálu

V tejto časti môžete definovať roly údajov a priradenia zobrazení údajov. Môžete tiež upraviť vizuál tak, aby zobrazoval názov hodnoty, ktorú zobrazuje.

Konfigurácia súboru možností

Upravte súbor capabilities.json tak, aby definoval rolu údajov, objekty a mapovanie zobrazenia údajov.

  • Definovanie roly údajov

    Definujte pole dataRoles s jedinou rolou údajov typu measure. Táto rola údajov sa nazýva measure a zobrazuje sa ako Measure. Umožňuje odovzdávanie poľa mierky alebo poľa so súhrnom.

    1. Otvorte súbor capabilities.json v nástroji VS Code.

    2. Odstráňte všetok obsah v poli dataRoles .

    3. Do poľa dataRoles vložte nasledujúci kód.

      {
    "displayName": "Measure",
    "name": "measure",
    "kind": "Measure"
}

    4. Uložte súbor capabilities.json.

  • Definovanie priradenia zobrazenia údajov

    V poli dataViewMappings definujte pole s názvom measure. Toto pole je možné odovzdať role údajov.

    1. Otvorte súbor capabilities.json v nástroji VS Code.

    2. Odstráňte všetok obsah v poli dataViewMappings .

    3. Do poľa dataViewMappings vložte nasledujúci kód.

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

    4. Uložte súbor capabilities.json.

Potvrďte, že súbor capabilities.json vyzerá takto:

{
    "dataRoles": [
        {
            "displayName": "Measure",
            "name": "measure",
            "kind": "Measure"
        }
    ],
    "dataViewMappings": [
        {
            "conditions": [
                { "measure": { "max": 1 } }
            ],
            "single": {
                "role": "measure"
            }
        }
    ],
    "privileges": []
}

(Voliteľné) Kontrola zmien kódu súboru možností

Overte, či vizuál kruhovej karty zobrazuje pole measure, a skontrolujte zmeny vykonané pomocou možnosti Zobraziť údaje.

  1. V služba Power BI otvorte zostavu Power BI US Sales Analysis (Analýza predaja v USA služby Power BI). Ak na vývoj vizuálu kruhovej karty používate inú zostavu, prejdite na túto zostavu.

  2. Všimnite si, že vizuál kruhovej karty teraz možno nakonfigurovať poľom s názvom Measure. Prvky môžete presúvať myšou z tably Polia do poľa Measure .

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

    Poznámka

    Projekt vizuálu ešte nezahŕňa logiku údajovej väzby.

  3. Na plávajúcom paneli s nástrojmi vyberte položku Zobraziť údaje.

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

  4. Výberom troch bodiek rozbaľte zobrazenie a výberom položky jeden zobrazte hodnotu.

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

  5. Rozbaľte položku metadata, potom pole columns a skontrolujte hodnoty format a displayName .

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

  6. Ak chcete prepnúť späť na vizuál, na paneli s nástrojmi plávajúcom nad vizuálom vyberte položku Zobraziť údaje.

Konfigurácia vizuálu na využívanie údajov

Vizuál sa zatiaľ vykreslí, ale nezobrazuje žiadne údaje. V tejto časti vykonáte zmeny v súbore visual.ts tak, aby vizuál kruhovej karty mohol využívať údaje.

  1. Otvorte súbor visual.ts v nástroji VS Code.

  2. V metóde update :

    • Pridajte nasledujúci príkaz ako prvý príkaz. Tento príkaz priradí objekt dataView premennej, aby sa uľahčil prístup, a deklaruje premennú, aby odkazla na objekt dataView .

      let dataView: DataView = options.dataViews[0];

    • Nahraďte reťazec .text("Value") týmto riadkom kódu:

      .text(<string>dataView.single.value)

    • Nahraďte reťazec .text("Label") týmto riadkom kódu:

      .text(dataView.metadata.columns[0].displayName)

  3. Uložte súbor visual.ts.

  4. Skontrolujte vizuál v služba Power BI.

Vizuál teraz zobrazuje názov a hodnotu vybratého údajového poľa.

Screenshot of a circle card visual displaying the quantity value.

Teraz ste vytvorili fungujúci vizuál služby Power BI. Môžete do nej pridať možnosti formátovania alebo ho môžete zabaliťpodľa potreby na okamžité použitie.

Súvisiaci obsah