Opplæring: Utvikle et sirkelkort i Power BI

  • Artikkel
  • 11 minutter å lese

I denne opplæringen skal du utvikle et visualobjekt i Power BI som heter sirkelkort, som viser en formatert målverdi i en sirkel. Sirkelkortet støtter tilpassing av fyllfargen og tykkelsen på omrisset.

I denne opplæringen lærer du hvordan du kan:

  • opprette et utviklingsprosjekt for visualobjektet
  • utvikle visualobjektet med visuelle D3-elementer
  • konfigurere visualobjektet til å behandle data
  • Konfigurer visualobjektet til å tilpasse seg størrelsesendringer.
  • Konfigurer adaptive farge- og kantlinjeinnstillinger for visualobjektet.

Obs!

Hvis du vil ha den fullstendige kildekoden for dette visualobjektet, kan du se sirkelkortet til Power BI-visualobjektet.

Forutsetninger

Før du begynner å utvikle visualobjektet i Power BI, må du bekrefte at du har alt som er oppført i denne delen.

Opprett et utviklingsprosjekt

I denne delen skal du opprette et prosjekt for sirkelkortvisualobjektet.

Obs!

I denne opplæringen brukes Visual Studio Code (VS Code) til å utvikle visualobjektet i Power BI.

  1. Åpne en ny terminal i VS Code , og gå til mappen du vil opprette prosjektet i.

  2. Skriv inn følgende kommando i PowerShell-terminalen:

    pbiviz new CircleCard

  3. Åpne CircleCard-mappen i VS Code Explorer. (Fil>Åpne mappe).

    Skjermbilde av VS Code-vinduet som er åpnet i sirkelkortmappen.

    Hvis du vil ha en detaljert forklaring av funksjonen for hver av disse filene, kan du se prosjektstrukturen i Power BI-visualobjektet.

  4. Kontroller terminalvinduet, og bekreft at du er i circleCard-katalogen. Installer avhengighetene for verktøyene for Power BI-visualobjekter.

    npm install

    Tips

    Hvis du vil se hvilke avhengigheter som er installert i visualobjektet, kan du se package.json-filen .

  5. Start sirkelkortet.

    pbiviz start

    Visualobjektet kjører nå mens det driftes på datamaskinen.

    Viktig

    Ikke lukk PowerShell-vinduet før slutten av opplæringen. Hvis du vil stoppe kjøringen av visualobjektet, skriver du inn CTRL+C , og hvis du blir bedt om å avslutte den satsvise jobben, skriver du inn Y og trykker ENTER.

Vis visualobjektet i Power Bi-tjeneste

Hvis du vil teste visualobjektet i Power Bi-tjeneste, bruker vi den amerikanske salgsanalyserapporten. Du kan laste ned denne rapporten og laste den opp til Power BI-tjenesten.

Du kan også bruke din egen rapport til å teste visualobjektet.

Obs!

Før du fortsetter, må du kontrollere at du har aktivert utviklerinnstillingene for visualobjekter.

  1. Logg deg på PowerBI.com, og åpne rapporten US Sales Analysis (salgsanalyse for USA) .

  2. Velg Rediger.

    Skjermbilde av redigeringsalternativet i Power B I-tjenesten.

  3. Opprett en ny side for testing ved å klikke på Ny side-knappen nederst i grensesnittet til Power BI-tjenesten.

    Skjermbilde av knappen ny side i Power B I-tjenesten.

  4. Velg Utviklervisualobjekt i Visualiseringer-ruten.

    Skjermbilde av visualobjektet for utviklere i visualiseringsruten.

    Dette visualobjektet representerer det egendefinerte visualobjektet du kjører på datamaskinen. Det er bare tilgjengelig når innstillingen egendefinert feilsøking av visualobjekt er aktivert.

  5. Bekreft at det ble lagt til et visualobjekt i rapportlerretet.

    Skjermbilde av det nye visualobjektet som er lagt til i rapporten.

    Dette er et enkelt visualobjekt som viser hvor mange ganger oppdateringsmetoden er kalt opp. Visualobjektet henter ikke data på dette stadiet.

    Obs!

    Hvis visualobjektet viser en feilmelding for tilkobling, åpner du en ny fane i nettleseren, navigerer til https://localhost:8080/assets og gir nettleseren tillatelse til å bruke denne adressen.

    Skjermbilde av det nye visualobjektet som viser en tilkoblingsfeil.

  6. Mens du velger det nye visualobjektet, kan du gå til Felter-ruten, utvide Sales (salg) og velge Quantity (antall) .

    Skjermbilde av power B I-tjenesteantallfeltet i salgstabellen i den amerikanske salgsanalyserapporten.

  7. Hvis du vil teste hvordan visualobjektet svarer, endrer du størrelsen på det og legger merke til at Update count (oppdateringsantall) stiger i verdi hver gang du endrer størrelse på visualobjektet.

    Skjermbilde av det nye visualobjektet som viser et annet antall oppdateringer, etter at størrelsen er endret.

Legg til visuelle elementer og tekst

I denne delen lærer du hvordan du gjør visualobjektet til en sirkel og får det til å vise tekst.

Endre filen for visualobjektet

Konfigurer visual.ts-filen .

Tips

For å forbedre lesbarheten anbefales det at du formaterer dokumentet hver gang du kopierer kodesnutter til prosjektet ditt. Høyreklikk hvor som helst i VS Code, og velg Formater dokument (ALT+SKIFT+F).

  1. Utvid src-mappen i Utforsker-ruten i VS Code, og velg filen visual.ts.

    Skjermbilde av tilgang til visual.ts-filen i V S-kode.

  2. Fjern all koden under MIT License-kommentaren.

    Viktig

    Legg merke til kommentarene øverst i visual.ts-filen. Tillatelse til å bruke pakkene for visualobjekter i Power BI gis gratis under vilkårene i MIT (Massachusetts Institute of Technology)-lisensen. Som en del av avtalen må du legge inn kommentarer øverst i filen.

  3. Importer bibliotekene og modulene som kreves, og definer typevalget for d3-biblioteket:

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

    Obs!

    Hvis D3 JavaScript-biblioteket ikke ble installert som en del av installasjonen, må du installere det nå. Kjør fra PowerShell npm i d3@latest --save

    Legg merke til at blant elementene du importerte, er:

    • IVisualHost – en samling av egenskaper og tjenester som brukes til å samhandle med verten for visualobjektet (Power BI).
    • D3-bibliotek – JavaScript-bibliotek for oppretting av datadrevne dokumenter.

  4. Opprett en tom visuell klasse under importen. Visualobjektklassen implementerer IVisual-grensesnittet der alle visualobjekter begynner:

    export class Visual implements IVisual {

}

    Hvis du vil ha informasjon om hva som går inn i visualobjektklassen, kan du se Visual API. I de neste tre trinnene skal vi definere denne klassen.

  5. Legg til private metoder på klassenivå i begynnelsen av visualobjektklassen :

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

    Legg merke til at noen av disse private metodene bruker valgtypen.

  6. Definer sirkel- og tekstelementene i konstruktørmetoden . Denne metoden kalles når visualobjektet startes. Med D3 Scalable Vector Graphics (SVG) kan du opprette tre figurer: en sirkel og to tekstelementer:

    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. Definer bredden og høyden i oppdateringsmetoden. Denne metoden kalles hver gang det er en endring i data- eller vertsmiljøet, for eksempel en ny verdi eller endring av størrelse.

    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. Lagre visual.ts-filen.

(Valgfritt) Se gjennom koden i visualobjektfilen

Kontroller at den endelige koden i visuals.ts-filen ser slik ut:

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

Endre egenskapsfilen

Sirkelkortvisualobjektet er et enkelt visualobjekt som ikke oppretter objekter i Format-ruten. Derfor kan du trygt fjerne objektdelen av filen.

  1. Åpne prosjektet i VS Code (Fil>Åpne mappe).

  2. Velg capabilities.json-filen.

    Skjermbilde av tilgang til capabilities.json-filen i V S-kode.

  3. Fjern hele objektmatrisen .
    Ikke la noen tomme linjer være mellom dataRoles og dataViewMappings.

  4. Lagre capabilities.json-filen.

Start sirkelkortet på nytt

Stans kjøringen av visualobjektet, og start det på nytt.

  1. Skriv inn CTRL+C i PowerShell-vinduet der du startet visualobjektet. Hvis du blir bedt om å avslutte den satsvise jobben, skriver du inn Y og trykker ENTER.

  2. Start visualobjektet på nytt i PowerShell.

    pbiviz start

Test visualobjektet med de tillagte elementene

Kontroller at visualobjektet viser de nylig tillagte elementene.

  1. Åpne rapportenPower BI US Sales Analysis (salgsanalyse for USA) i Power BI-tjenesten. Hvis du bruker en annen rapport til å utvikle sirkelkortet, går du til denne rapporten.

  2. Dra en verdi til Mål-boksen , og kontroller at visualobjektet er formet som en sirkel.

    Skjermbilde av sirkelkortet som er formet som en sirkel.

    Hvis visualobjektet ikke viser noe, drar du Quantity (antall) -feltet fra feltruten inn i utviklervisualobjektet.

  3. Endre størrelsen på visualobjektet.

    Legg merke til at sirkelen og teksten skaleres til dimensjonen for visualobjektet. Oppdateringsmetoden kalles opp når du endrer størrelse på visualobjektet, og derfor skaleres elementene i visualobjektet på nytt.

Aktiver automatisk innlasting

Bruk denne innstillingen for å sikre at visualobjektet automatisk lastes inn på nytt hver gang du lagrer endringer i prosjektet.

  1. Gå til rapporten Power BI US Sales Analysis (salgsanalyse for USA) (eller til prosjektet som har sirkelkortet ditt).

  2. Velg sirkelkortet.

  3. Velg Aktiver/deaktiver automatisk innlasting på den flytende verktøylinjen.

    Skjermbilde av å klikke alternativet aktiver/deaktiver automatisk innlasting på sirkelkortet på den flytende verktøylinjen for sirkelkortet.

Få visualobjektet til å behandle data

I denne delen definerer du dataroller og datavisningstilordninger. Du kan også endre visualobjektet til å vise navnet på verdien det viser.

Konfigurer egenskapsfilen

Endre capabilities.json-filen for å definere datarollen, objektene og datavisningstilordningene.

  • Definer datarollen

    Definer dataRoles-matrisen med én datarolle av typen mål. Denne datarollen kalles mål og vises som Mål. Den gjør det mulig å sende et målfelt eller et felt som skal summeres.

    1. Åpne capabilities.json-filen i VS Code.

    2. Fjern alt innholdet i dataRoles-matrisen .

    3. Sett inn denne koden i dataRoles-matrisen.

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

    4. Lagre capabilities.json-filen.

  • Definer datavisningstilordningen

    Definer et felt kalt mål i dataViewMappings-matrisen . Dette feltet kan sendes til datarollen.

    1. Åpne capabilities.json-filen i VS Code.

    2. Fjern alt innholdet i dataViewMappings-matrisen .

    3. Sett inn følgende kode i dataViewMappings-matrisen.

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

    4. Lagre capabilities.json-filen.

Bekreft at capabilities.json-filen ser slik ut:

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

(Valgfritt) Se gjennom kodeendringer i egenskapsfilen

Kontroller at sirkelkortet viser målfeltet, og se gjennom endringene du har gjort, ved hjelp av alternativet Vis datavisning.

  1. Åpne rapportenPower BI US Sales Analysis (salgsanalyse for USA) i Power BI-tjenesten. Hvis du bruker en annen rapport til å utvikle sirkelkortet, går du til denne rapporten.

  2. Legg merke til at sirkelkortet nå kan konfigureres med et felt kalt mål. Du kan dra og slippe elementer fra Felter-ruten til Mål-feltet.

    Skjermbilde av sirkelkortmålingen som er arkivert, i Power Bi-tjeneste visualiseringsruten.

    Obs!

    Det visuelle prosjektet inneholder ikke logikk for databinding ennå.

  3. Velg Vis datavisning på den flytende verktøylinjen.

    Skjermbilde av vis datavisning-knappen, som er plassert på den flytende verktøylinjen for sirkelkortet.

  4. Velg de tre prikkene for å utvide visningen, og velg enkel for å vise verdien.

    Skjermbilde av verdifiguren slik den vises i sirkelkortet, viser alternativet for datavisning.

  5. Utvid metadata, deretter matrisen columns, og se gjennom verdiene format og displayName.

    Skjermbilde av format- og visningsnavnverdiene som vises i sirkelkortet, viser datavisningsalternativet.

  6. Hvis du vil veksle tilbake til visualobjektet, kan du velge Vis datavisning i verktøylinjen som flyter over visualobjektet.

Konfigurer visualobjektet til å bruke data

Så langt gjengis visualobjektet, men viser ingen data. I denne delen skal du gjøre endringer i visual.ts-filen , slik at sirkelkortvisualobjektet kan bruke data.

  1. Åpne visual.ts-filen i VS Code.

  2. I oppdateringsmetoden :

    • Legg til denne setningen som den første setningen. Setningen tilordner dataView til en variabel for enkel tilgang og erklærer at variabelen skal referere til dataView-objektet.

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

    • Erstatt .text("Value") med denne kodelinjen:

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

    • Erstatt .text("Label") med denne kodelinjen:

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

  3. Lagre visual.ts-filen.

  4. Se gjennom visualobjektet i Power BI-tjenesten.

Visualobjektet viser nå navnet og verdien til det valgte datafeltet.

Skjermbilde av et sirkelkort-visualobjekt som viser antallsverdien.

Du har nå opprettet et power bi-visualobjekt som fungerer. Du kan legge til formateringsalternativer i den, eller du kan pakke den som den er for umiddelbar bruk.

Neste trinn