Zelfstudie: Een visual van een cirkelkaart ontwikkelen in Power BI

Als ontwikkelaar kunt u uw eigen Power BI-visuals maken. Deze visuals kunnen door uzelf worden gebruikt, door uw organisatie of door derden.

In deze zelfstudie ontwikkelt u een Power BI-visual met de naam CircleCard waarin een opgemaakte meetwaarde wordt weergegeven in een cirkel. U kunt de opvulkleur en randbreedte van de visual van een cirkelkaart aanpassen.

In deze zelfstudie leert u het volgende:

Vereisten

Voordat u begint met het ontwikkelen van uw Power BI-visual controleert u of u over alles beschikt wat hieronder wordt vermeld.

• Een Power BI Pro of Premium PPU-account (per gebruiker). Als u geen sleutel hebt, kunt u zich registreren voor een gratis proefversie.

• Visual Studio Code (VS Code). VS Code is een ideale IDE (Integrated Development Environment) voor het ontwikkelen van JavaScript- en TypeScript-toepassingen.

• Windows PowerShell versie 4 of hoger (voor Windows). Of Terminal (voor OSX).

• Een omgeving die is voorbereid voor het ontwikkelen van een Power BI-visual. Lees hier hou u uw omgeving instelt voor het ontwikkelen van een Power BI-visual.

• In deze zelfstudie wordt het rapport US Sales Analysis gebruikt. U kunt dit rapport downloaden en uploaden naar Power BI service of uw eigen rapport gebruiken. Als u meer wilt weten over Power BI-service en bestanden en het uploaden van bestanden, raadpleegt u de zelfstudie Aan de slag met de Power BI-service.

Een ontwikkelingsproject maken

In dit gedeelte maakt u een project voor de visual CircleCard.

1. Open PowerShell en navigeer naar de map waarin u uw project wilt maken.

2. Voer de volgende opdracht in:

   pbiviz new CircleCard
   

3. Navigeer naar de projectmap.

   cd CircleCard
   

4. Start de visual CircleCard. Uw visual wordt nu uitgevoerd terwijl deze wordt gehost op uw computer.

   pbiviz start
   

   Belangrijk

   Sluit het PowerShell-venster pas aan het einde van de zelfstudie. Als u wilt voorkomen dat de visual wordt uitgevoerd, voert u Ctrl+C in en als u wordt gevraagd de batch-taak te beëindigen, voert u Y in en drukt u op Enter.

De visual in de Power BI weergeven

Als u de visual in Power BI service wilt testen, gebruiken we het rapport Verkoopanalyse vs. U kunt dit rapport downloaden en uploaden naar de Power BI-service.

U kunt ook uw eigen rapport gebruiken om de visual te testen.

1. Meld u aan bij PowerBI.com en open het rapport US Sales Analysis.

2. Selecteer Meer opties > Bewerken.

   

3. Maak een nieuwe pagina om te testen door op de knop Nieuwe pagina te klikken onderaan de interface van de Power BI-service.

   

4. Selecteer de visual Ontwikkelaar in het deelvenster Visualisaties.

   

   Deze visual (of visualisatie) staat voor de aangepaste visual die op uw computer wordt uitgevoerd. Deze optie is alleen beschikbaar wanneer de instelling Aangepaste visuele foutopsporing inschakelen met de visual voor ontwikkelaars is ingeschakeld.

5. Kijk of er een visual is toegevoegd aan het rapportcanvas.

   

   Dit is een eenvoudige visual die aangeeft hoe vaak de Update-methode van de visual is aangeroepen. Op dit moment is dat nul omdat de visual nog geen gegevens ophaalt.

   Notitie

   Als in de visual een bericht over een verbindingsfout wordt weergegeven, opent u een nieuw tabblad in de browser, gaat u naar https://localhost:8080/assets/status en geeft u uw browser toestemming om dit adres te gebruiken.

   

6. Selecteer de nieuwe visual, ga naar het deelvenster Velden, vouw Sales uit en selecteer Quantity.

   

7. Als u wilt testen hoe de visual reageert, wijzigt u het formaat van de visual. U ziet dan dat de waarde voor Update count telkens wordt verhoogd wanneer u het formaat van de visual wijzigt.

   

Visuele elementen en tekst toevoegen

In dit gedeelte leert u hoe u van het visuele element een cirkel maakt en hoe u er tekst in kunt weergeven.

Het visual-bestand wijzigen

Pas het bestand visual.ts aan door een paar regels code te verwijderen en toe te voegen.

1. Open het project in VS Code (File > Open Folder).

2. Vouw in het deelvenster Explorer de map src uit en selecteert het bestand visual.ts.

   

   Belangrijk

   Bekijk de opmerkingen bovenaan het bestand visual.ts. U ziet dat u in overeenstemming met de voorwaarden van de MIT-licentie (Massachusetts Institute of Technology) gratis gebruik kunt maken van de pakketten met aangepaste Power BI-visuals. Als onderdeel van de overeenkomst moet u de opmerkingen aan de bovenkant van het bestand laten staan.

3. Verwijder de volgende regels met code uit het bestand visual.ts.

   • De regel voor het importeren van de VisualSettings:

     import { VisualSettings } from "./settings";
     

   • De vier declaraties voor privévariabelen op klasseniveau.

   • Alle coderegels binnen de constructor.

   • Alle coderegels binnen de methode update.

   • Alle resterende coderegels binnen de methode update, waaronder de methoden parseSettings en enumerateObjectInstances.

4. Voeg de volgende regels met code toe aan het einde van de sectie import:

   • IVisualHost: een verzameling eigenschappen en services die kunnen worden gebruikt voor interactie met de visual-host (Power BI).

     import IVisualHost = powerbi.extensibility.IVisualHost;
     

   • D3-bibliotheek

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

     Notitie

     Als u deze bibliotheek niet hebt geselecteerd tijdens de installatie, installeert u de D3-bibliotheek van JavaScript.

5. Voeg onder de klassedeclaratie Visual de volgende eigenschappen op klasseniveau in. U hoeft alleen de coderegels toe te voegen die beginnen met 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. Sla het bestand visual.ts op.

Een cirkel en tekstelementen toevoegen

Voeg D3 SVG (Scalable Vector Graphics) toe. Hierdoor kunt u drie vormen maken: een cirkel en twee tekstelementen.

1. Open visual.ts in VS Code.

2. Voeg de volgende code toe aan de constructor.

   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

   Om de leesbaarheid te verbeteren, wordt het aanbevolen om het document steeds opnieuw op te maken als u codefragmenten hebt ingevoegd. Klik hiervoor met de rechtermuisknop ergens in VS Code en selecteer Format Document (Alt+Shift+F).

3. Sla het bestand visual.ts op.

De breedte en hoogte instellen

Stel de breedte en hoogte van de visual in, om vervolgens de kenmerken en stijlen van de elementen van de visual te initialiseren.

1. Open visual.ts in VS Code.

2. Voeg de volgende code toe aan de updatemethode.

   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. Sla het bestand visual.ts op.

(Optioneel) De code in het visual-bestand controleren

Controleer of de code in het bestand visual.ts er als volgt uitziet:

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

Het capabilities-bestand wijzigen

Verwijder overbodige regels met code uit het capabilities-bestand.

1. Open het project in VS Code (File > Open Folder).

2. Selecteer het bestand capabilities.json.

   

3. Verwijder alle objectelementen (regels 14-60).

4. Sla het bestand capabilities.json op.

De visual CircleCard opnieuw starten

Stop de uitvoering van de visual en start deze opnieuw.

1. Voer in het PowerShell-venster met de visual Ctrl+C in en als u wordt gevraagd de batch-taak te beëindigen, voert u Y in en drukt u op Enter.

2. Start de visual in PowerShell.

   pbiviz start
   

De visual testen met de toegevoegde elementen

Controleer of de zojuist toegevoegde elementen worden weergegeven in de visual.

1. Open in de Power BI-service het rapport US Sales Analysis. Als u een ander rapport gebruikt voor het ontwikkelen van een cirkelkaart, gaat u naar dat rapport.

2. Zorg ervoor dat de visual de vorm van een cirkel heeft.

   

   Notitie

   Als de visual leeg is, sleept u het veld Quantity vanuit het deelvenster Fields naar de visual Ontwikkelaar.

3. Wijzig het formaat van de visual.

   U ziet dat de schaal van de cirkel en tekst wordt aangepast aan de afmetingen van de visual. De methode Update wordt aangeroepen wanneer u het formaat van de visual wijzigt, en als gevolg hiervan wordt de schaal van de visuele elementen opnieuw aangepast.

Automatisch opnieuw laden inschakelen

U kunt instellen dat de visual automatisch opnieuw wordt geladen wanneer u projectwijzigingen opslaat.

1. Ga naar het rapport US Sales Analysis (of naar het project met uw visual van een cirkelkaart).

2. Selecteer de visual van de cirkelkaart

3. Selecteer Automatisch opnieuw laden in-/uitschakelen op de zwevende werkbalk.

   

Gegevens verwerken in de visual

In dit gedeelte definieert u gegevensrollen en toewijzingen van gegevensweergaven. U gaat de visual ook aanpassen om de naam weer te geven van de waarde in de visual.

Het capabilities-bestand configureren

Bewerk het bestand capabilities.json zo dat de toewijzingen voor de gegevensrol en gegevensweergave worden gedefinieerd.

• De gegevensrol definiëren

  Definieer de matrix dataRoles met één gegevensrol van het type Measure. Deze gegevensrol krijgt de naam measure en wordt weergegeven als Measure. Door deze gegevensrol kan er nu een meetveld worden doorgegeven, of een samengevat veld.

  1. Open het bestand capabilities.json in VS Code.

  2. Verwijder alle inhoud van de matrix dataRoles (regels 3-12).

  3. Voeg de volgende code toe aan de matrix dataRoles.

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

  4. Sla het bestand capabilities.json op.

• De toewijzing van de gegevensweergave definiëren

  Definieer een veld met de naam meting in de matrix dataViewMappings. Dit veld kan worden doorgegeven aan de gegevensrol.

  1. Open het bestand capabilities.json in VS Code.

  2. Verwijder alle inhoud van de matrix dataViewMappings (regels 10-30).

  3. Voeg de volgende code toe aan de matrix dataViewMappings.

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

  4. Sla het bestand capabilities.json op.

(Optioneel) De codewijzigingen in het capabilities-bestand controleren

Controleer of in de visual van de cirkelkaart het veld measure wordt weergegeven en controleer de wijzigingen die u hebt aangebracht met behulp van de op Show Dataview.

1. Open in de Power BI-service het rapport US Sales Analysis. Als u een ander rapport gebruikt voor het ontwikkelen van een cirkelkaart, gaat u naar dat rapport.

2. U ziet dat de visual nu kan worden geconfigureerd met een veld met de naam Measure. U kunt elementen vanuit het deelvenster Velden slepen naar het veld Measure.

   

   Notitie

   Het visualproject bevat nog geen logica voor gegevensbinding.

3. Selecteer DataView weergeven op de zwevende werkbalk.

   

4. Selecteer de drie puntjes om de weergave uit te vouwen en selecteer enkel om de waarde weer te geven.

   

5. Vouw metadata uit en daarna de matrix columns. Bekijk vervolgens de waarden voor format en displayName.

   

6. Als u weer terug wilt naar de visual, selecteert u DataView weergeven in de werkbalk die boven de visual zweeft.

<a name="configure-the-visual-to-consume-data">De visual configureren om gegevens te gebruiken

Pas het bestand visual.ts zo aan dat de visual van de cirkelkaart gegevens kan gebruiken.

1. Open het bestand visual.ts in VS Code.

2. Zorg ervoor dat de volgende regel wordt weergegeven in het bestand om de interface uit de DataView module te powerbi importeren. Als het bestand niet in het bestand staat, voegt u het toe.

   import DataView = powerbi.DataView;
   

3. Ga als volgt te werk in de update-methode:

   • Voeg de volgende instructie toe als de eerste instructie. Deze instructie wijst dataView toe aan een variabele voor eenvoudige toegang en declareert de variabele om te verwijzen naar het object dataView.

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

   • Vervang .text("waarde") door deze regel code:

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

   • Vervang .text("label") door deze regel code:

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

4. Sla het bestand visual.ts op.

5. Bekijk de visual in de Power BI-service.

In de visual worden nu de naam en waarde van het geselecteerde gegevensveld weergegeven.

U hebt nu een werkende visual Power BI visual. U kunt er opmaakopties aan toevoegen of u kunt deze verpakken zoals ze zijn voor direct gebruik.

Volgende stappen