Zelfstudie: Een visual van een cirkelkaart in Power BI ontwikkelen

In deze zelfstudie ontwikkelt u een Power BI-visual met de naam cirkelkaart waarmee een opgemaakte metingswaarde in een cirkel wordt weergegeven. De visual van de cirkelkaart ondersteunt het aanpassen van opvulkleur en omtrekdikte.

In deze zelfstudie leert u het volgende:

  • Maak een ontwikkelingsproject voor uw visual.
  • Ontwikkel uw visual met D3-visualelementen.
  • Configureer uw visual om gegevens te verwerken.
  • Configureer uw visual om aan te passen aan wijzigingen in de grootte.
  • Configureer adaptieve kleur- en randinstellingen voor uw visual.

Notitie

Zie de Power BI-visual van de cirkelkaart voor de volledige broncode van deze visual.

Vereisten

Controleer voordat u begint met het ontwikkelen van uw Power BI-visual of alles in deze sectie wordt vermeld.

Een ontwikkelingsproject maken

In deze sectie maakt u een project voor de visual van de cirkelkaart.

Notitie

In deze zelfstudie wordt Visual Studio Code (VS Code) gebruikt voor het ontwikkelen van de Power BI-visual.

  1. Open een nieuwe terminal in VS Code en navigeer naar de map waarin u uw project wilt maken.

  2. Voer de volgende opdracht in de PowerShell-terminal in:

    pbiviz new CircleCard
    
  3. Open de map CircleCard in vs Code Explorer. (Map bestand>openen).

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

    Zie de projectstructuur van power BI-visuals voor een gedetailleerde uitleg van de functie van elk van deze bestanden.

  4. Controleer het terminalvenster en controleer of u zich in de map circleCard bevindt. Installeer de afhankelijkheden van power BI-visualhulpprogramma's.

    npm install
    

    Tip

    Als u wilt zien welke afhankelijkheden in uw visual zijn geïnstalleerd, controleert u het bestand package.json .

  5. Start de visual van de cirkelkaart.

    pbiviz start
    

    Uw visual wordt nu uitgevoerd terwijl deze wordt gehost op uw computer.

    Belangrijk

    Sluit het PowerShell-venster niet tot het einde van de zelfstudie. Als u wilt voorkomen dat de visual wordt uitgevoerd, voert u Ctrl+C in en als u wordt gevraagd om de batchtaak te beëindigen, voert u Y en vervolgens Enter in.

De visual weergeven in de Power BI-service

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

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

Notitie

Controleer voordat u doorgaat of u de instellingen voor ontwikkelaars van visuals hebt ingeschakeld.

  1. Meld u aan bij PowerBI.com en open het rapport Verkoopanalyse in de VERENIGDE STATEN.

  2. Selecteer Bewerken.

    Screenshot of the edit option in Power B I service.

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

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

  4. Selecteer in het deelvenster Visualisaties de visual Voor ontwikkelaars.

    Screenshot of the developer visual in the visualizations pane.

    Deze visual vertegenwoordigt de aangepaste visual die u op uw computer uitvoert. Deze is alleen beschikbaar wanneer de instelling voor foutopsporing van aangepaste visuals is ingeschakeld.

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

    Screenshot of the new visual added to the report.

    Dit is een eenvoudige visual die het aantal keren weergeeft dat de updatemethode is aangeroepen. In deze fase haalt de visual geen gegevens op.

    Notitie

    Als in de visual een verbindingsfout wordt weergegeven, opent u een nieuw tabblad in uw browser, gaat u naar https://localhost:8080/assetsen autoriseert u uw browser om dit adres te gebruiken.

    Screenshot of the new visual displaying a connection error.

  6. Terwijl de nieuwe visual is geselecteerd, gaat u naar het deelvenster Velden, vouwt u Verkoop uit en selecteert u Hoeveelheid.

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

  7. Als u wilt testen hoe de visual reageert, wijzigt u het formaat ervan en ziet u dat de waarde voor het aantal updates steeds wordt verhoogd wanneer u het formaat van de visual wijzigt.

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

Visuele elementen en tekst toevoegen

In deze sectie leert u hoe u uw visual kunt omzetten in een cirkel en hoe deze tekst weergeeft.

Het visualbestand wijzigen

Stel het bestand visual.ts in.

Tip

Om de leesbaarheid te verbeteren, is het raadzaam om het document telkens op te maken wanneer u codefragmenten naar uw project kopieert. Klik met de rechtermuisknop op een willekeurige plaats in VS-code en selecteer Document opmaken (of voer Alt+Shift+F in).

  1. Vouw in VS Code in het deelvenster Explorer de src-map uit en selecteer de bestandsvisual.ts.

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

  2. Verwijder alle code onder de opmerking van de MIT-licentie.

    Belangrijk

    Let op de opmerkingen boven aan het bestand visual.ts . Toestemming om de Power BI-visualpakketten te gebruiken, wordt gratis verleend volgens de voorwaarden van de MIT-licentie (Massachusetts Institute of Technology). Als onderdeel van de overeenkomst moet u de opmerkingen boven aan het bestand achterlaten.

  3. Importeer de benodigde bibliotheken en modules en definieer de typeselectie voor de d3-bibliotheek:

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

    Notitie

    Als de D3 JavaScript-bibliotheek niet is geïnstalleerd als onderdeel van uw installatie, installeert u deze nu. Voer vanuit PowerShell de opdracht uit npm i d3@latest --save

    Zoals u ziet, zijn de items die u hebt geïmporteerd:

    • IVisualHost : een verzameling eigenschappen en services die worden gebruikt voor interactie met de visualhost (Power BI).
    • D3-bibliotheek - JavaScript-bibliotheek voor het maken van gegevensgestuurde documenten.
  4. Maak onder de importbewerkingen een lege visualklasse . De visualklasse implementeert de IVisual-interface waar alle visuals beginnen:

    export class Visual implements IVisual {
    
    }
    

    Zie Visual-API voor meer informatie over wat er in de visualklasse wordt weergegeven. In de volgende drie stappen definiëren we deze klasse.

  5. Voeg privémethoden op klasseniveau toe aan het begin van de visualklasse:

    private host: IVisualHost;
    private svg: Selection<SVGElement>;
    private container: Selection<SVGElement>;
    private circle: Selection<SVGElement>;
    private textValue: Selection<SVGElement>;
    private textLabel: Selection<SVGElement>;
    

    U ziet dat sommige van deze privémethoden het selectietype gebruiken.

  6. Definieer de cirkel- en tekstelementen in de constructormethode . Deze methode wordt aangeroepen wanneer de visual wordt geïnstantieerd. Met de SVG (Scalable Vector Graphics) van D3 kunt u drie vormen maken: een cirkel en twee tekstelementen:

    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. Definieer de breedte en hoogte in de updatemethode. Deze methode wordt elke keer aangeroepen wanneer er een wijziging in de gegevens- of hostomgeving is, zoals een nieuwe waarde of het wijzigen van de grootte.

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

(Optioneel) De code in het visuals-bestand controleren

Controleer of de uiteindelijke 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 "./../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");
    }
}

Het mogelijkhedenbestand wijzigen

De visual van de cirkelkaart is een eenvoudige visual waarmee geen objecten worden gemaakt in het deelvenster Opmaak. Daarom kunt u de objectensectie van het bestand veilig verwijderen.

  1. Open uw project in VS Code (map bestand>openen).

  2. Selecteer het bestand capabilities.json .

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

  3. Verwijder de hele objectenmatrix .
    Laat geen lege regels tussen dataRoles en dataViewMappings achter.

  4. Sla het bestand capabilities.json op.

De visual van de cirkelkaart opnieuw starten

Stop de uitvoering van de visual en start deze opnieuw.

  1. Voer Ctrl+C in het PowerShell-venster waarin u de visual hebt gestart. Als u wordt gevraagd de batchtaak te beëindigen, voert u Y in en voert u Vervolgens Enter in.

  2. Start de visual opnieuw in PowerShell.

    pbiviz start
    

De visual testen met de toegevoegde elementen

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

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

  2. Sleep een waarde naar het vak Meting en zorg ervoor dat de visual is gevormd als een cirkel.

    Screenshot of the circle card visual shaped as a circle.

    Als de visual niets weergeeft, sleept u vanuit het deelvenster Velden het veld Hoeveelheid naar de visual voor ontwikkelaars.

  3. Pas het formaat van de visual aan.

    U ziet dat de cirkel- en tekstschaal passen bij de afmetingen van de visual. De updatemethode wordt aangeroepen wanneer u het formaat van de visual wijzigt, waardoor de visuele elementen opnieuw worden geschaald.

Automatisch opnieuw laden inschakelen

Gebruik deze instelling om ervoor te zorgen dat de visual automatisch opnieuw wordt geladen telkens wanneer u projectwijzigingen opslaat.

  1. Navigeer naar het Power BI US Sales Analysis-rapport (of naar het project met de visual van uw cirkelkaart).

  2. Selecteer de visual van de cirkelkaart.

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

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

De visual ophalen om gegevens te verwerken

In deze sectie definieert u gegevensrollen en toewijzingen voor gegevensweergaven. U wijzigt ook de visual om de naam weer te geven van de waarde die wordt weergegeven.

Het mogelijkhedenbestand configureren

Wijzig het bestand capabilities.json om de toewijzingen van de gegevensrol, objecten en gegevensweergaven te definiëren.

  • De gegevensrol definiëren

    Definieer de dataRoles-matrix met één gegevensrol van de typemeting. Deze gegevensrol wordt meting genoemd en wordt weergegeven als Meting. Hiermee kunt u een metingveld of een opgeteld veld doorgeven.

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

    2. Verwijder alle inhoud in de dataRoles-matrix .

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

      {
          "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 dataViewMappings-matrix . Dit veld kan worden doorgegeven aan de gegevensrol.

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

    2. Verwijder alle inhoud in de dataViewMappings-matrix .

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

      {
          "conditions": [
              { "measure": { "max": 1 } }
          ],
          "single": {
              "role": "measure"
          }
      }
      
    4. Sla het bestand capabilities.json op.

Controleer of uw capabilities.json-bestand er als volgt uitziet:

{
    "dataRoles": [
        {
            "displayName": "Measure",
            "name": "measure",
            "kind": "Measure"
        }
    ],
    "dataViewMappings": [
        {
            "conditions": [
                { "measure": { "max": 1 } }
            ],
            "single": {
                "role": "measure"
            }
        }
    ],
    "privileges": []
}

(Optioneel) De wijzigingen in de bestandscode van de mogelijkheden controleren

Controleer of in de visual van de cirkelkaart het metingveld wordt weergegeven en controleer de wijzigingen die u hebt aangebracht met behulp van de optie Dataview weergeven .

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

  2. U ziet dat de visual van de cirkelkaart nu kan worden geconfigureerd met een veld met de titel Measure. U kunt elementen uit het deelvenster Velden slepen en neerzetten in het veld Meting .

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

    Notitie

    Het visuele project bevat nog geen logica voor gegevensbinding.

  3. Selecteer Dataview weergeven in de zwevende werkbalk.

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

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

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

  5. Vouw metagegevens uit, vervolgens de matrix met kolommen en controleer de waarden voor format en displayName.

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

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

De visual configureren om gegevens te gebruiken

Tot nu toe wordt de visual weergegeven, maar worden er geen gegevens weergegeven. In deze sectie gaat u wijzigingen aanbrengen in het bestand visual.ts , zodat de visual van de cirkelkaart gegevens kan gebruiken.

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

  2. In de updatemethode :

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

      let dataView: DataView = options.dataViews[0];
      
    • Vervang .text("Value") door deze regel code:

      .text(<string>dataView.single.value)
      
    • Vervang .text("Label") door deze regel code:

      .text(dataView.metadata.columns[0].displayName)
      
  3. Sla het bestand visual.ts op.

  4. Bekijk de visual in het Power BI-service.

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

Screenshot of a circle card visual displaying the quantity value.

U hebt nu een werkende Power BI-visual gemaakt. U kunt er opmaakopties aan toevoegen of u kunt deze inpakken voor direct gebruik.