Selvstudium: Udvikl en Power BI-cirkelkortvisualisering

Som udvikler kan du oprette dine egne Power BI-visualiseringer. Disse visualiseringer kan bruges af dig, din organisation eller af tredjeparter.

I dette selvstudium lærer du, hvordan du udvikler en Power BI-visualisering kaldet et cirkelkort, der viser en formateret måleværdi i en cirkel. Cirkelkortvisualiseringen understøtter tilpasning af udfyldningsfarven og konturens tykkelse.

I dette selvstudium lærer du, hvordan du gør følgende:

Forudsætninger

Før du begynder at udvikle din Power BI-visualisering, skal du bekræfte, at du har alt, hvad der er angivet i denne sektion.

• en Power BI Pro -eller Premium pr. bruger (PPU)- konto. Hvis du ikke har en, kan du tilmelde dig en gratis prøve.

• Visual Studio Code (VS Code). VS Code er et ideelt IDE (integreret udviklingsmiljø) til udvikling af JavaScript- og TypeScript-programmer.

• Windows PowerShell version 4 eller nyere (til Windows). Eller Terminal (til OSX).

• Et miljø, der er klar til udvikling af en Power BI-visualisering. Konfigurer dit miljø til udvikling af en Power BI-visualisering.

• I dette selvstudium bruges US Sales Analysis-rapporten. du kan downloade denne rapport og overføre den til Power BI tjeneste eller bruge din egen rapport. Hvis du har brug for flere oplysninger om Power BI-tjenesten og uploade filer, kan du se selvstudiet Kom i gang med at oprette i Power BI-tjenesten.

Opret et udviklingsprojekt

I dette afsnit opretter du et projekt til cirkelkortvisualiseringen.

1. Åbn PowerShell , og Naviger til den mappe, du vil oprette dit projekt i.

2. Angiv følgende kommando:

   pbiviz new CircleCard
   

3. Naviger til projektets mappe.

   cd CircleCard
   

4. Start cirkelkortvisualiseringen. Din visualisering kører nu, mens den hostes på din computer.

   pbiviz start
   

   Vigtigt

   Luk ikke PowerShell -vinduet, før du afslutter selvstudiet. Hvis du vil forhindre, at det visuelle element kører, skal du skrive CTRL + C , og hvis du bliver bedt om at afslutte batchjobbet, skal du skrive Y og trykke på Enter.

få vist det visuelle element i Power BI tjeneste

Vi bruger rapporten US Sales Analysis til at teste visualiseringen i Power BI servicen. Du kan downloade denne rapport og uploade den til Power BI-tjenesten.

Du kan også bruge din egen rapport til at teste visualiseringen.

1. Log på PowerBI.com, og åbn US Sales Analysis-rapporten.

2. Vælg Flere indstillinger > Rediger.

   

3. Opret en ny side til test ved at klikke på knappen Ny side nederst i grænsefladen i Power BI-tjenesten.

   

4. I ruden Visualiseringer skal du markere Udviklervisualisering.

   

   Denne visualisering repræsenterer den brugerdefinerede visualisering, som kører på din computer. Den er kun tilgængelig, når indstillingen fejlfinding af brugerdefineret visualisering er aktiveret.

5. Bekræft, at der blev føjet en visualisering til rapportlærredet.

   

   Dette er en simpel visualisering, der viser det antal gange, som metoden update er blevet kaldt. I denne fase henter visualiseringen ingen data.

   Bemærk

   Hvis der vises en fejlmeddelelse for forbindelsen i visualiseringen, skal du åbne en ny fane i din browser, navigere til https://localhost:8080/assets/status og give din browser tilladelse til at bruge denne adresse.

   

6. Med den nye visualisering valgt skal du gå til ruden Felter, udvide Salg og markere Mængde.

   

7. Hvis du vil teste, hvordan visualiseringen reagerer, skal du tilpasse størrelsen af den og bemærke, hvordan værdien Opdater antal øges, hver gang du tilpasser størrelsen af visualiseringen.

   

Tilføj visualiseringer og tekst

I dette afsnit lærer du, hvordan du omdanner din visualisering til en cirkel og får den til at vise tekst.

Rediger filen visuals

Konfigurer filen visual.ts ved at slette og tilføje nogle få kodelinjer.

1. Åbn dit projekt i VS Code (Filer > Åbn mappe).

2. I ruden Stifinder skal du udvide mappen src og vælge filen visual.ts.

   

   Vigtigt

   Læg mærke til kommentarerne øverst i filen visual.ts. Tilladelse til at bruge Power BI-visualiseringspakker tildeles gratis i henhold til vilkårene i MIT-licensen (Massachusetts Institute of Technology). Som en del af aftalen skal du lade kommentarerne øverst i filen stå.

3. Fjern følgende kodelinjer fra filen visual.ts.

   • VisualSettings-importen:

     import { VisualSettings } from "./settings";
     

   • De fire erklæringer om private variabler på klasseniveau.

   • Alle kodelinjer i konstruktøren.

   • Alle kodelinjer i metoden update.

   • Alle resterende kodelinjer under metoden update, herunder metoderne parseSettings og enumerateObjectInstances.

4. Føj følgende kodelinjer til slutningen af importafsnittet:

   • IVisualHost – En samling egenskaber og tjenester, der bruges til at interagere med visualiseringsværten (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>;
     

     Bemærk

     Hvis du ikke har installeret dette bibliotek som en del af din konfiguration, skal du installere D3 JavaScript-biblioteket.

5. Under erklæringen for klassen Visual skal du indsætte følgende egenskaber for klasseniveau. Du skal kun tilføje kodelinjer, der 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. Gem filen visual.ts.

Tilføj en cirkel og tekstelementer

Tilføj D3 Scalable Vector Graphics (SVG). Dette gør det muligt at oprette tre figurer: en cirkel og to tekstelementer.

1. Åbn visual.ts i VS Code.

2. Føj følgende kode til 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);
   

   Tip

   Hvis du vil forbedre læsbarheden, anbefales det, at du formaterer dokumentet, hver gang du kopierer kodestykker til dit projekt. Højreklik et vilkårligt sted i VS Code, og vælg Formatér dokument (Alt + Skift + F).

3. Gem filen visual.ts.

Angiv bredde og højde

Angiv visualiseringens bredde og højde, og initialiser attributterne og typografierne for visualiseringens elementer.

1. Åbn visual.ts i VS Code.

2. Føj følgende kode til metoden update.

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

(Valgfri) Gennemse koden i filen visuals

Bekræft, at koden i filen visuals.ts ligner følgende:

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

Rediger filen capabilities

Slet unødvendige kodelinjer fra filen capabilities.

1. Åbn dit projekt i VS Code (Filer > Åbn mappe).

2. Vælg filen capabilities.json.

   

3. Fjern alle elementer fra objektet (linje 14-60).

4. Gem filen capabilities.json.

Genstart cirkelkortvisualiseringen

Stop kørslen af visualiseringen, og genstart den.

1. I PowerShell -vinduet, der kører det visuelle element, skal du skrive CTRL + C, og hvis du bliver bedt om at afslutte batchjobbet, skal du skrive Y og trykke på Enter.

2. Åbn det visuelle element i PowerShell.

   pbiviz start
   

Test visualiseringen med de tilføjede elementer

Bekræft, at de nyligt tilføjede elementer vises i visualiseringen.

1. Åbn Power BI US Sales Analysis-rapporten i Power BI-tjenesten. Hvis du bruger en anden rapport til at udvikle cirkelkortvisualiseringen, skal du navigere til den pågældende rapport.

2. Sørg for, at visualiseringen er formet som en cirkel.

   

   Bemærk

   Hvis der ikke vises noget i visualiseringen, skal du fra ruden Felter trække feltet Mængde til udviklervisualiseringen.

3. Tilpas størrelsen af visualiseringen.

   Bemærk, at cirklen og teksten er skaleret til at passe til dimensionerne af visualiseringen. Metoden update kaldes, når du tilpasser størrelsen af visualiseringen igen, og derfor bliver visualiseringens elementer omskaleret.

Aktivér automatisk genindlæsning

Brug denne indstilling til at sikre, at visualiseringen automatisk genindlæses, hver gang du gemmer ændringer af projektet.

1. Naviger til Power BI US Sales Analysis-rapporten (eller til det projekt, der indeholder din cirkelkortvisualisering).

2. Vælg cirkelkortvisualiseringen.

3. Vælg Skift automatisk genindlæsning i den flydende værktøjslinje.

   

Hent visualiseringen for at behandle data

I dette afsnit definerer du dataroller og tilknytninger af datavisninger. Du redigerer også visualiseringen for at vist navnet på den værdi, den viser.

Konfigurer filen capabilities

Rediger filen capabilities.json for at definere datarollen og tilknytningerne af datavisninger.

• Definition af datarollen

  Definer matrixen dataRoles med en enkelt datarolle for typen measure. Denne datarolle kaldes for measure og vises som Måling. Det muliggør videregivelse af enten feltet measure eller et felt, der opsummeres.

  1. Åbn filen capabilities.json i VS Code.

  2. Fjern alt indhold i matrixen dataRoles (linje 3-12).

  3. Indsæt følgende kode i matrixen dataRoles.

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

  4. Gem filen capabilities.json.

• Definition af tilknytningen af datavisningen

  Definer et felt med navnet måling i matrixen dataViewMappings . Dette felt kan videregives til datarollen.

  1. Åbn filen capabilities.json i VS Code.

  2. Fjern alt indhold i matrixen dataViewMappings (linje 10-30).

  3. Indsæt følgende kode i matrixen dataViewMappings.

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

  4. Gem filen capabilities.json.

(Valgfri) Gennemse kodeændringer i filen capabilities

Bekræft, at feltet measure vises i cirkelkortvisualiseringen, og gennemse de ændringer, du foretager, ved hjælp af indstillingen Vis DataView.

1. Åbn Power BI US Sales Analysis-rapporten i Power BI-tjenesten. Hvis du bruger en anden rapport til at udvikle cirkelkortvisualiseringen, skal du navigere til den pågældende rapport.

2. Bemærk, at cirkelkortvisualiseringen nu kan konfigureres med et felt med titlen Måling. Du kan trække og slippe elementer fra ruden Felter til feltet Måling.

   

   Bemærk

   Visualiseringsprojektet indeholder endnu ikke logik, der binder data.

3. Vælg Vis datavisning i den flydende værktøjslinje.

   

4. Vælg de tre prikker for at udvide visningen, og vælg enkelt for at få vist værdien.

   

5. Udvid metadata, derefter matrixen columns og gennemse værdierne format og displayName.

   

6. Hvis du vil skifte tilbage til visualiseringen, skal du vælge Vis datavisning på værktøjslinjen, der flyder over visualiseringen.

<a name="configure-the-visual-to-consume-data">Konfigurer visualiseringen til at bruge data

Foretag ændringer af filen visual.ts, så cirkelkortvisualiseringen kan bruge data.

1. Åbn filen visual.ts i VS Code.

2. Sørg for, at følgende linje vises i filen for at importere DataView grænsefladen fra powerbi modulet. Hvis den ikke findes i filen, skal du tilføje den.

   import DataView = powerbi.DataView;
   

3. Gør følgende i metoden update:

   • Tilføj følgende sætning som den første sætning. Sætningen tildeler dataView til en variabel for at give nem adgang og deklarerer variablen for at referere til dataView-objektet.

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

   • Erstat .text("Value") med denne kodelinje:

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

   • Erstat .text("Label") med denne kodelinje:

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

4. Gem filen visual.ts.

5. Gennemse visualiseringen i Power BI-tjenesten.

Det visuelle element viser nu navnet på og værdien for det markerede datafelt.

du har nu oprettet et arbejds Power BI visuelt element. Du kan føje formateringsindstillinger til den, eller du kan pakke den, så den er til øjeblikkelig brug.

Næste trin