Opplæring: Utvikle et sirkelkort i Power BI

Som utvikler kan du opprette dine egne visualobjekter i Power BI. Disse visualobjektene kan brukes av deg, av organisasjonen eller av tredjeparter.

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 for å tilpasse seg størrelsesendringer.
  • Konfigurer innstillinger for adaptiv farge og kantlinje for visualiseringen.

Obs!

Hvis du vil ha fullstendig kildekode for dette visualobjektet, kan du se Power BI visualobjekt .

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 kan du opprette et prosjekt for sirkelkortet.

  1. Åpne PowerShell og naviger til mappen du vil opprette prosjektet i.

  2. Skriv inn denne kommandoen:

    pbiviz new CircleCard
    
  3. Gå til prosjektmappen.

    cd CircleCard
    
  4. Start sirkelkortet. Visualobjektet kjører nå mens det driftes på datamaskinen.

    pbiviz start
    

    Viktig!

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

Vis visualobjektet i Power BI tjenesten

For å teste visualobjektet Power BI tjenesten, bruker vi rapporten Salgsanalyse USA. 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 Flere alternativer > Rediger.

    Skjermbilde av redigeringsalternativet i Power BI-tjenesten.

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

    Skjermbilde av Ny side-knappen i Power BI-tjenesten.

  4. Velg Utviklervisualobjekt i Visualiseringer-ruten.

    Skjermbilde av utviklervisualobjekt i Visualiseringer-ruten.

    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/status 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 kvantitetsfeltet i Power BI-tjenesten i salgstabellen i rapporten salgsanalyse for USA.

  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 oppdateringsantall 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.

Obs!

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

Endre filen for visualobjektet

Konfigurer visual.ts-filen ved å slette og legge til noen linjer med kode.

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

  2. Utvid src-mappen i Utforsker-ruten, og velg filen visual.ts.

    Skjermbilde av tilgangen til visual.ts-filen i VS-kode.

    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. Fjern følgende kodelinjer fra visual.ts-filen.

    • VisualSettings-importen:

      import { VisualSettings } from "./settings";
      
    • De fire klassenivådeklarasjonene for private variabler.

    • Alle kodelinjene i konstruktøren.

    • Alle kodelinjene i oppdateringsmetoden.

    • Alle gjenværende kodelinjer i oppdateringsmetoden, inkludert metodene parseSettings og enumerateObjectInstances.

  4. Legg til følgende kodelinjer på slutten av importdelen:

    • IVisualHost – en samling av egenskaper og tjenester som brukes til å samhandle med verten for visualobjektet (Power BI).

      import IVisualHost = powerbi.extensibility.IVisualHost;
      
    • D3-bibliotek

      import * as d3 from "d3";
      type Selection<T extends d3.BaseType> = d3.Selection<T, any,any, any>;
      

      Obs!

      Hvis du ikke installerte dette biblioteket som en del av oppsettet, kan du installere D3 JavaScript-biblioteket.

  5. Sett inn disse egenskapene for klassenivå under klassedeklarasjonen Visual (visualobjekt) . Du trenger bare å legge til kodelinjene som starter med private.

    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>;
        // ...
    }
    
  6. Lagre visual.ts-filen.

Legg til en sirkel og tekstelementer

Legg til D3 Scalable Vector Graphics (SVG). Dette gjør det mulig å opprette tre figurer: en sirkel og to tekstelementer.

  1. Åpne visual.ts i VS Code.

  2. Legg til denne koden for konstruktøren.

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

    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).

  3. Lagre visual.ts-filen.

Angi bredde og høyde

Angi bredden og høyden på visualobjektet, og initialiser deretter attributtene og stilene for elementene i visualobjektet.

  1. Åpne visual.ts i VS Code.

  2. Legg til denne koden for oppdateringsmetoden.

    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");
    
  3. Lagre visual.ts-filen.

(Valgfritt) Se gjennom koden i visualobjektfilen

Kontroller at 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 "core-js/stable";
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 EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
import VisualObjectInstance = powerbi.VisualObjectInstance;
import DataView = powerbi.DataView;
import VisualObjectInstanceEnumerationObject = powerbi.VisualObjectInstanceEnumerationObject;
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

Slett unødvendige kodelinjer fra egenskapsfilen.

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

  2. Velg capabilities.json-filen.

    Skjermbilde av tilgangen til capabilities.ts-filen i VS-kode.

  3. Fjern alle objektelementene (linje 14–60).

  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 som kjører visualobjektet, og hvis du blir bedt om å avslutte den satsvise jobben, skriver du inn Y og trykker Enter.

  2. Start visualobjektet i PowerShell.

    pbiviz start
    

Test visualobjektet med de tillagte elementene

Kontroller at visualobjektet viser de nylig tillagte elementene.

  1. Åpne rapporten Power 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. Sørg for at visualobjektet er formet som en sirkel.

    Skjermbilde av sirkelkortet formet som en sirkel.

    Obs!

    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 klikking på alternativet Aktiver/deaktiver automatisk innlasting på den flytende verktøylinjen i 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 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 (linje 3-12).

    3. Sett inn denne koden i dataRoles-matrisen.

      {
          "displayName": "Measure",
          "name": "measure",
          "kind": "Measure"
      }
      
    4. Lagre capabilities.json-filen.

  • Definer tilordningen av datavisning

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

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

    2. Fjern alt innhold i dataViewMappings-matrisen (linje 10–30).

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

      {
          "conditions": [
              { "measure": { "max": 1 } }
          ],
          "single": {
              "role": "measure"
          }
      }
      
    4. Lagre capabilities.json-filen.

(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 rapporten Power 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 målfilen for sirkelkortet i visualiseringsruten i Power BI-tjenesten.

    Obs!

    Det visuelle prosjektet inneholder ikke logikk for databinding ennå.

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

    Skjermbilde av Vis datavisning-knappen på den flytende verktøylinjen i sirkelkortet.

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

    Skjermbilde av verditallet slik det vises i Vis datavisning-alternativet i sirkelkortet.

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

    Skjermbilde av verdiene for format og visningsnavn slik det vises i Vis datavisning-alternativet i sirkelkortet.

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

<a name="configure-the-visual-to-consume-data">Konfigurer visualobjektet til å bruke data

Gjør endringer i visual.ts-filen, slik at sirkelkortet kan bruke data.

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

  2. Sørg for at følgende linje vises i filen for å importere DataView grensesnittet fra powerbi modulen. Hvis det ikke er i filen, kan du legge den til.

    import DataView = powerbi.DataView;
    
  3. Gjør følgende 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)
      
  4. Lagre visual.ts-filen.

  5. Se gjennom visualobjektet i Power BI-tjenesten.

Den visuelle effekten viser nå navnet og verdien til det valgte data feltet.

du har nå opprettet en aktiv Power BI visuell effekt. Du kan legge til formaterings alternativer i den, eller du kan pakke den som er for umiddelbar bruk.

Neste trinn