Självstudie: Utveckla ett visuellt Power BI-objekt i form av ett cirkelkort

Som utvecklare kan du skapa egna visuella Power BI-objekt. Dessa visuella objekt kan användas av dig, din organisation eller tredje parter.

Den här självstudien kommer du att utveckla ett visuellt Power BI-objekt med namnet Cirkelkort för att visa ett formaterat måttvärde inuti en cirkel. Det visuella cirkelkort-objektet stöder anpassning av fyllningsfärg och konturtjocklek.

I den här guiden får du lära dig att:

Förutsättningar

Innan du börjar utveckla visuella Power BI-objekt bör du kontrollera att du har allt som anges i det här avsnittet.

• Ett Power BI Pro-Premium-konto (PPU) per användare. Om du inte har redan har en kan du registrera dig för en kostnadsfri utvärderingsversion.

• Visual Studio Code (VS Code). VS Code är en perfekt Integrated Development Environment (IDE) för utveckling av Java Script-och TypeScript-program.

• Windows PowerShell version 4 eller senare (för Windows). Eller Terminal (för OSX).

• En miljö redo för att utveckla ett visuellt Power BI-objekt. Konfigurera din miljö för att utveckla ett visuellt Power BI-objekt.

• I den här självstudien används rapporten US Sales Analysis. Du kan ladda ned den här rapporten och ladda upp den Power BI tjänsten eller använda en egen rapport. Mer information om Power BI-tjänsten och uppladdning av filer hittar du i självstudien Kom igång med att skapa i Power BI-tjänsten.

Skapa ett utvecklingsprojekt

I det här avsnittet kommer du att skapa ett projekt för det visuella cirkelkort-objektet.

1. Öppna PowerShell och navigera till den mapp som du vill skapa projektet i.

2. Ange följande kommando:

   pbiviz new CircleCard
   

3. Gå till projektets mapp.

   cd CircleCard
   

4. Starta det visuella cirkelkort-objektet. Ditt visuella objekt körs nu samtidigt som det finns på datorn.

   pbiviz start
   

   Viktigt

   Stäng inte PowerShell-fönstret förrän i slutet av självstudien. Om du vill stoppa det visuella objektet från att köras anger du Ctrl+C. Om du uppmanas att avsluta batchjobbet anger du Y och trycker på Retur.

Visa det visuella objektet i Power BI tjänsten

För att testa det visuella Power BI-tjänsten använder vi rapporten us Sales Analysis. Du kan Hämta den här rapporten och överföra den till Power BI-tjänsten.

Du kan också använda din egen rapport för att testa det visuella objektet.

1. Logga in på PowerBI.com och öppna rapporten US Sales Analysis.

2. Välj Fler alternativ > Redigera.

   

3. Skapa en ny sida för testning genom att klicka på knappen Ny sida längst ned i Power BI-tjänstens gränssnitt.

   

4. Välj Visuellt objekt för utvecklare i fönstret Visualiseringar.

   

   Den här visuella objektet representerar det anpassade visuella objektet som du kör på datorn. Den är endast tillgänglig när inställningen anpassad visuell felsökning är aktiverad.

5. Verifiera att ett visuellt objekt har lagts till på rapportarbetsytan.

   

   Det här är ett enkelt visuellt objekt som visar hur många gånger uppdateringsmetoden har anropats. I det här skedet hämtar det visuella objektet inte några data.

   Anteckning

   Om det visuella objektet visar ett meddelande om anslutningsfel, öppnar du en ny flik i webbläsaren, navigerar till https://localhost:8080/assets/status och auktoriserar webbläsaren att använda den här adressen.

   

6. Medan det nya visuella objektet är markerat går du till rutan Fält, expanderar Försäljning och väljer Antal.

   

7. Du kan testa hur det visuella objektet svarar genom att ändra storlek på det och notera att Uppdateringsantalets värde ökar varje gång du ändrar storlek på det visuella objektet.

   

Lägga till visuella element och text

I det här avsnittet får du lära dig hur du förvandlar ditt visuella objekt till en cirkel och gör att det kan visa text.

Ändra de visuella objektens fil

Konfigurera visual.ts-filen genom att ta bort och lägga till några rader kod.

1. Öppna ditt projekt i VS Code (Fil > Öppna mapp).

2. Utvidga mappen src i Explorer-fönstret och välj visual.ts.

   

   Viktigt

   Lägg märke till kommentarerna överst i filen visual.ts. Behörighet att använda de anpassade visuella paketen i Power BI beviljas kostnadsfritt i enlighet med villkoren för MIT-licensen (Massachusetts Institute of Technology). Som en del av avtalet, måste du lämna kommentarer överst i filen.

3. Ta bort följande kodrader från filen visual.ts.

   • VisualSettings-import:

     import { VisualSettings } from "./settings";
     

   • De fyra privata variabeldeklarationerna på klassnivå.

   • Alla kodrader inuti konstruktorn.

   • Alla kodrader inuti metoden uppdatera.

   • Alla återstående kodrader under metoden Uppdatera, inklusive metoderna parseSettings och enumerateObjectInstances.

4. Lägg till följande rader med kod i slutet av avsnittet Importera:

   • IVisualHost – en samling egenskaper och tjänster som används för att interagera med den visuella värden (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>;
     

     Anteckning

     Installera D3 JavaScript-biblioteket om du inte har installerat det som en del av installationen.

5. Under klassdeklarationen Visuella objekt infogar du följande klassnivåegenskaper. Du behöver bara lägga till kodraderna som börjar 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. Spara filen visual.ts.

Lägga till en cirkel och textelement

Lägg till D3 Scalable Vector Graphics (SVG). På så sätt kan du skapa tre former: en cirkel och två textelement.

1. Öppna visual.ts i VS Code.

2. Lägg till följande kod till konstruktorn.

   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

   Om du vill förbättra läsbarheten rekommenderar vi att du formaterar dokumentet varje gång som du kopierar kodfragment till projektet. Högerklicka på valfri plats i VS Code och välj Formatera dokument (Alt + Skift + F).

3. Spara filen visual.ts.

Ange bredd och höjd

Ange bredden och höjden på det visuella objektet och initiera attribut och format för de visuella elementen.

1. Öppna visual.ts i VS Code.

2. Lägg till följande kod till uppdateringsmetoden.

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

(Valfritt) Granska koden i de visuella objektens fil

Kontrollera att koden i filen visuals.ts ser ut så här:

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

Ändra funktionsfilen

Ta bort onödiga kodrader från funktionsfilen.

1. Öppna ditt projekt i VS Code (Fil > Öppna mapp).

2. Spara filen capabilities.json.

   

3. Ta bort alla objektelement (raderna 14–60).

4. Spara filen capabilities.json.

Starta om det visuella cirkelkort-objektet

Stoppa det visuella objektet från att köras och starta om det.

1. I PowerShell-fönstret som kör det visuella objektet anger du Ctrl+C. Om du uppmanas att avsluta batchjobbet anger du Y och trycker på Retur.

2. Starta det visuella objektet i PowerShell.

   pbiviz start
   

Testa det visuella objektet med de tillagda elementen

Kontrollera att det visuella objektet visar de nyligen tillagda elementen.

1. I Power BI-tjänsten öppnar du rapporten Power BI US Sales Analysis. Om du använder en annan rapport för att utveckla det visuella cirkelkort-objektet, navigerar du till rapporten.

2. Se till att det visuella objektet är format som en cirkel.

   

   Anteckning

   Om det visuella objektet inte visar något, drar du fältet Kvantitet från fönstret Fält till det visuella objektet för utvecklare.

3. Ändra storlek på det visuella objektet.

   Observera att cirkeln och texten skalas för att de anpassas till det visuella objektets utrymme. Uppdateringsmetoden anropas när du ändrar storlek på det visuella objektet och detta resulterar i att visuella element skalas om.

Aktovera automatisk återinläsning

Använd denna inställning för att se till att det visuella objektet läses in igen varje gång du sparar ändringarna i projektet.

1. Gå till rapporten Power BI US Sales Analysis (eller till projektet som har det visuella cirkelkort-objektet).

2. Välj det visuella cirkelkort-objektet.

3. I det flytande verktygsfältet väljer du Växla automatisk återinläsning.

   

Hämta det visuella objektet för att bearbeta data

I det här avsnittet definierar du dataroller och datavymappningar. Du kan också ändra det visuella objektet så att det visar namnet på det värde som visas.

Konfigurera funktionsfilen

Definiera datarollen och datavymappningarna genom att ändra filen capabilities.json.

• Definiera datarollen

  Definiera matrisen dataRoles med en enda dataroll av typen mått. Den här datarollen kallas mått och visas som Mått. Den gör det möjligt att skicka ett måttfält eller ett fält som har summerats.

  1. Öppna filen capabilities.json i VS Code.

  2. Ta bort allt innehåll i matrisen dataRoles (raderna 3–12).

  3. Infoga följande kod i matrisen dataRoles.

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

  4. Spara filen capabilities.json.

• Definiera datavymappningen

  Definiera ett fält med namnet mått i matrisen dataViewMappings. Det här fältet kan skickas till datarollen.

  1. Öppna filen capabilities.json i VS Code.

  2. Ta bort allt innehåll (raderna 10–30) från matrisen dataViewMappings.

  3. Infoga följande kod i matrisen dataViewMappings.

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

  4. Spara filen capabilities.json.

(Valfritt) Granska kodändringar i funktionsfilen

Kontrollera att det visuella kortet visar fältet mått och granska ändringarna som du har gjort med alternativet Visa datavy.

1. I Power BI-tjänsten öppnar du rapporten Power BI US Sales Analysis. Om du använder en annan rapport för att utveckla det visuella cirkelkort-objektet, navigerar du till rapporten.

2. Observera att det visuella cirkelkort-objektet nu kan konfigureras med ett fält med rubriken Mått. Du kan dra och släppa element från fönstret Fält till fältet Mått.

   

   Anteckning

   Det visuella projektet inkluderar ännu inte databindningslogik.

3. I det flytande verktygsfältet väljer du Visa datavy.

   

4. Välj de tre punkterna för att expandera visningen och välj enskild för att visa värdet.

   

5. Expandera metadata, sedan matrisen kolumner och granska formatering och displayName-värden.

   

6. Välj Visa datavy i det flytande verktygsfältet ovanför det visuella objektet om du vill växla tillbaka till det visuella objektet.

Konfigurera det visuella objektet för att använda data

Gör ändringar i filen visual.ts, så att det visuella kortet kommer att kunna använda data.

1. Öppna filen visual.ts i VS Code.

2. Kontrollera att följande rad visas i filen för att importera DataView gränssnittet från powerbi modulen. Om den inte finns i filen lägger du till den.

   import DataView = powerbi.DataView;
   

3. Gör följande i metoden uppdatera:

   • Lägg till följande instruktion som den första instruktionen. Instruktionen tilldelar dataView till en variabel för enkel åtkomst, och deklarerar variabeln så att den refererar till objektet dataView.

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

   • Ersätt .text(”värde”) med den här kodraden:

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

   • Ersätt .text(”etikett”) med den här kodraden:

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

4. Spara filen visual.ts.

5. Granska det visuella objektet i Power BI-tjänsten.

Det visuella objektet visar nu namn och värde för det valda datafältet.

Nu har du skapat ett fungerande Power BI visuellt objekt. Du kan lägga till formateringsalternativ i den eller så kan du paketera det som det är för omedelbar användning.

Nästa steg