Opplæring: Utvikle et sirkelkort for Power BI

  • Artikkel

I denne opplæringen utvikler du et Power BI-visualobjekt kalt sirkelkort som viser en formatert målverdi i en sirkel. Sirkelkortvisualobjektet støtter tilpassing av fyllfarge og konturtykkelse.

I denne opplæringen lærer du hvordan du kan gjøre følgende:

  • Opprett et utviklingsprosjekt for visualobjektet.
  • Utvikle visualobjektet med D3-visuelle elementer.
  • Konfigurer visualobjektet til å behandle data.
  • Konfigurer visualobjektet til å tilpasse seg størrelsesendringer.
  • Konfigurer innstillinger for adaptiv farge og kantlinje for visualobjektet.

Merk

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

Forutsetning

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

Opprette et utviklingsprosjekt

I denne delen oppretter du et prosjekt for sirkelkortvisualobjektet.

Merk

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

  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. (Åpne filmappe>).

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

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

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

    npm install

    Tips

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

  5. Start sirkelkortvisualobjektet.

    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 hindre at visualobjektet kjører, skriver du inn CTRL+C, og hvis du blir bedt om å avslutte den satsvise jobben, skriver du inn Y og deretter ENTER.

Vise 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-tjeneste.

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

Merk

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

  1. Logg på PowerBI.com , og åpne den amerikanske salgsanalyserapporten .

  2. Velg Rediger.

    Screenshot of the edit option in Power B I service.

  3. Opprett en ny side for testing ved å klikke på Ny side-knappen nederst i Power Bi-tjeneste-grensesnittet.

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

  4. Velg Visualobjekt for utviklere i Visualiseringer-ruten.

    Screenshot of the developer visual in the visualizations pane.

    Dette visualobjektet representerer det egendefinerte visualobjektet du kjører på datamaskinen. Den er bare tilgjengelig når innstillingen for feilsøking av egendefinerte visualobjekter er aktivert.

  5. Kontroller at et visualobjekt ble lagt til i rapportlerretet.

    Screenshot of the new visual added to the report.

    Dette er et enkelt visualobjekt som viser antall ganger oppdateringsmetoden har blitt kalt. På dette stadiet henter ikke visualobjektet noen data.

    Merk

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

    Screenshot of the new visual displaying a connection error.

  6. Når det nye visualobjektet er valgt, går du til Felter-ruten , utvider Salg og velger Antall.

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

  7. Hvis du vil teste hvordan visualobjektet reagerer, endrer du størrelsen på det og legger merke til at oppdateringsverdien øker hver gang du endrer størrelsen på visualobjektet.

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

Legge til visuelle elementer og tekst

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

Endre visualobjektfilen

Konfigurer visual.ts-filen .

Tips

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

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

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

  2. Fjern all koden under MIT-lisenskommentaren.

    Viktig

    Legg merke til kommentarene øverst i visual.ts-filen . Tillatelse til å bruke Power BI-visualobjektpakkene gis gratis i henhold til vilkårene i Massachusetts Institute of Technology (MIT)-lisensen. Som en del av avtalen må du legge igjen kommentarene ø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>;

    Merk

    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 den visuelle verten (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 definerer vi 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. D3 Skalerbar vektorgrafikk (SVG) gjør det mulig å 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ørrelsen.

    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 visual.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 noen objekter i Format-ruten. Derfor kan du trygt fjerne objektdelen av filen.

  1. Åpne prosjektet i VS Code (Åpne filmappe>).

  2. Velg capabilities.json-filen.

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

  3. Fjern hele objektmatrisen .
    Ikke la noen tomme linjer stå mellom dataRoles og dataViewMappings.

  4. Lagre capabilities.json-filen.

Start sirkelkortvisualobjektet på nytt

Stopp 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 deretter ENTER.

  2. Start visualobjektet på nytt i PowerShell.

    pbiviz start

Test visualobjektet med de ekstra elementene

Kontroller at visualobjektet viser de nylig tilføyde elementene.

  1. Åpne salgsanalyserapporten for Power BI US i Power Bi-tjeneste. Hvis du bruker en annen rapport til å utvikle sirkelkortvisualobjektet, går du til rapporten.

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

    Screenshot of the circle card visual shaped as a circle.

    Hvis visualobjektet ikke viser noe, drar du Antall-feltet fra Felt-ruten til utviklervisualobjektet.

  3. Endre størrelsen på visualobjektet.

    Legg merke til at sirkel- og tekstskalaen passer til dimensjonene til visualobjektet. Oppdateringsmetoden kalles når du endrer størrelsen på visualobjektet, og visualobjektelementene blir derfor skalert på nytt.

Aktiver automatisk innlasting på nytt

Bruk denne innstillingen til å sikre at visualobjektet laster inn på nytt hver gang du lagrer prosjektendringer.

  1. Gå til salgsanalyserapporten for Power BI (eller til prosjektet som har sirkelkortvisualobjektet).

  2. Velg sirkelkortvisualobjektet.

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

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

Få visualobjektet til å behandle data

I denne delen definerer du dataroller og datavisningstilordninger. Du endrer også visualobjektet for å vise navnet på verdien den viser.

Konfigurer egenskapsfilen

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

  • Definer datarollen

    Definer dataRoles-matrisen med én enkelt datarolle for typemålet. Denne datarollen kalles mål, og vises som Mål. Det gjør det mulig å sende enten et målfelt eller et felt som er oppsummert.

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

    2. Fjern alt innholdet i dataRoles-matrisen.

    3. Sett inn følgende kode 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 endringer i filkode for funksjoner

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

  1. Åpne salgsanalyserapporten for Power BI US i Power Bi-tjeneste. Hvis du bruker en annen rapport til å utvikle sirkelkortvisualobjektet, går du til rapporten.

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

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

    Merk

    Visualobjektprosjektet inneholder ennå ikke databindingslogikk.

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

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

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

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

  5. Utvid metadata, deretter kolonnematrisen, og se gjennom format- og displayName-verdiene.

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

  6. Hvis du vil veksle tilbake til visualobjektet, velger du Vis datavisning på verktøylinjen som flyter over visualobjektet.

Konfigurere visualobjektet til å bruke data

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

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

  2. I oppdateringsmetoden:

    • Legg til følgende setning som den første setningen. Setningen tilordner dataView til en variabel for enkel tilgang, og deklarerer variabelen for å 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-tjeneste.

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

Screenshot of a circle card visual displaying the quantity value.

Du har nå opprettet et fungerende Power BI-visualobjekt. Du kan legge til formateringsalternativer i det, eller du kan pakke det som det er for umiddelbar bruk.

Relatert innhold