Een dialoogvenster voor uw Power BI-visual maken

Wanneer u een visual maakt, is het soms handig om aanvullende informatie weer te geven aan de klant in een afzonderlijk venster. U kunt bijvoorbeeld het volgende doen:

• Aanvullende informatie weergeven - zoals een tekstnotitie of een video
• Een dialoogvenster voor invoergegevens weergeven - zoals een datumdialoogvenster

Voor deze doeleinden kunt u een pop-upvenster voor dialoogvensters maken, een dialoogvenster genaamd in dit artikel.

Overwegingen in het dialoogvenster

Wanneer u een dialoogvenster voor uw visual maakt, moet u rekening houden met het volgende:

• Tijdens de ontwikkeling kunt u de grootte en positie van het dialoogvenster opgeven.
• Wanneer het dialoogvenster wordt geactiveerd, wordt de achtergrond van het rapport grijs weergegeven.
• De dialoogvensterkop bevat het pictogram van de visual en de weergavenaam als titel.
• Het dialoogvenster kan maximaal drie actieknoppen bevatten. U kunt kiezen welke knoppen u uit een bepaalde selectie wilt weergeven.
• In het dialoogvenster wordt een uitgebreide HTML gebruikt iframe.
• Terwijl het dialoogvenster wordt weergegeven, kan er geen actie worden uitgevoerd in het rapport totdat het wordt gesloten.
• De dialoogvenstercode kan externe NPM-bibliotheken gebruiken, net als de visual.

Belangrijk

Het dialoogvenster mag niet spontaan worden geactiveerd. Dit moet het directe resultaat zijn van een gebruikersactie.

Een dialoogvenster voor uw visual ontwerpen

Als u een dialoogvenster wilt configureren, moet u twee onderdelen toevoegen aan uw code:

• Een implementatiebestand : het is raadzaam om voor elk dialoogvenster een implementatiebestand te maken.
• Code voor het aanroepen van het dialoogvenster : voeg code toe aan het bestand om het visual.ts dialoogvenster aan te roepen.

Het implementatiebestand voor het dialoogvenster maken

U wordt aangeraden een implementatiebestand te maken voor elk dialoogvenster dat u maakt. Plaats de dialoogvensterbestanden in de src map:

Elk implementatiebestand van het dialoogvenster moet de volgende onderdelen bevatten:

• Een dialoogvensterklasse
• Een resultaatklasse
• Registratie van de dialoogvensterklasse

Een dialoogvensterklasse maken

Maak een dialoogvensterklasse voor het dialoogvenster. De initialState parameter wordt openModalDialog doorgegeven aan de aannemer van het dialoogvenster bij het maken ervan. Gebruik het initialState object om parameters door te geven aan het dialoogvenster om het gedrag of uiterlijk ervan te beïnvloeden.

De dialoogvenstercode kan deze IDialogHost methoden gebruiken:

• IDialogHost.setResult(result:object) - De dialoogvenstercode retourneert een resultaatobject dat wordt doorgestuurd naar de aanroepende visual.
• IDialogHost.close(actionId: DialogAction, result?:object) - De dialoogvenstercode kan het dialoogvenster programmatisch sluiten en een resultaatobject teruggeven aan de aanroepende visual.

Importeert boven op het bestand:

import powerbi from "powerbi-visuals-api";
import DialogConstructorOptions = powerbi.extensibility.visual.DialogConstructorOptions;
import DialogAction = powerbi.DialogAction;
// React imports as an example
import * as ReactDOM from 'react-dom';
import * as React from 'react';
import reactDatepicker from 'react-datepicker';
import 'react-datepicker/dist/react-datepicker.css';

Voor dit voorbeeld moeten deze pakketten worden geïnstalleerd:

    npm i react-dom react react-datepicker

Klasserealisatie:

export class DatePickerDialog {
    static id = "DatePickerDialog";

    constructor(options: DialogConstructorOptions, initialState: object) {
        const host = options.host;
        let pickedDate: Date;
        const startDate = new Date(initialState['startDate']);
        
        // Dialog rendering implementation
        ReactDOM.render(
            React.createElement(
                reactDatepicker,
                {
                    inline: true,
                    openToDate: startDate,
                    onChange: (date: Date) => {
                        pickedDate = date
                        host.setResult({ date: pickedDate })
                    }
                },
                null),
            options.element
        );

        document.addEventListener('keydown', e => {
            if (e.code == 'Enter' && pickedDate) {
                host.close(DialogAction.Close, {date: pickedDate});
            }
        });
    }
}

Een resultaatklasse maken

Maak een klasse die het resultaat van het dialoogvenster retourneert en voeg deze vervolgens toe aan het implementatiebestand van het dialoogvenster.

In het onderstaande voorbeeld retourneert de DatePickerDialogResult klasse een datumtekenreeks.

export class DatePickerDialogResult {
    date: string;
}

Het dialoogvenster toevoegen aan de registerlijst

Elk dialoogvenster-implementatiebestand moet een registerreferentie bevatten. Voeg de twee regels in het onderstaande voorbeeld toe aan het einde van het implementatiebestand van het dialoogvenster. De eerste regel moet identiek zijn in elk implementatiebestand van het dialoogvenster. Op de tweede regel wordt het dialoogvenster weergegeven; wijzig deze op basis van de naam van de dialoogvensterklasse.

globalThis.dialogRegistry = globalThis.dialogRegistry || {};
globalThis.dialogRegistry[DatePickerDialog.id] = DatePickerDialog;

Het dialoogvenster aanroepen

Voordat u een dialoogvenster maakt, moet u bepalen welke knoppen het bevat. Power BI-visuals ondersteunen de volgende zes dialoogvensterknoppen:

export enum DialogAction {
        Close = 0,
        OK = 1,
        Cancel = 2,
        Continue = 3,
        No = 4,
        Yes = 5
    }

Elk dialoogvenster dat u maakt, moet worden aangeroepen in het visual.ts bestand. In dit voorbeeld wordt het dialoogvenster gedefinieerd met twee actieknoppen.

import powerbi from "powerbi-visuals-api";
import DialogAction = powerbi.DialogAction;
const dialogActionsButtons = [DialogAction.OK, DialogAction.Cancel];

In dit voorbeeld wordt het dialoogvenster aangeroepen door op een visualknop te klikken. De knop Visual wordt gedefinieerd als onderdeel van de visuele constructor in het visual.ts bestand.

De grootte en positie van het dialoogvenster definiëren

Vanuit API-versie 4.0 of hoger kunt u de grootte en positie van het dialoogvenster definiëren met behulp van de DialogOpenOptions parameter van openModalDialog. Als u wilt weten welke versie u gebruikt, controleert u het apiVersionbestand pbiviz.json .

    export interface RectSize {
        width: number;
        height: number;
    }

    export interface DialogOpenOptions {
        title: string;
        size?: RectSize;
        position?: VisualDialogPosition;
        actionButtons: DialogAction[];
    }

Met de positieparameter kunt u bepalen waar het dialoogvenster moet worden geopend op het scherm. U kunt ervoor kiezen om het dialoogvenster in het midden van het scherm te openen of u kunt een andere positie definiëren ten opzichte van de visual.

    const enum VisualDialogPositionType {
        Center = 0,
        RelativeToVisual = 1
    }

    export interface VisualDialogPosition {
        type: VisualDialogPositionType;
        left?: number;
        top?: number;
    }

• Als er geen type is opgegeven, is het standaardgedrag om het dialoogvenster in het midden te openen.
• De positie wordt weergegeven in pixels ten opzichte van de linkerbovenhoek van de visual.

In dit voorbeeld ziet u een dialoogvenster voor datumselectie van 250 x 300 pixels van 100 pixels links en 30 pixels onder de bovenkant van de visual:

export class Visual implements IVisual {
    private target: HTMLElement;
    private host: IVisualHost;
 
    constructor(options: VisualConstructorOptions) {
        this.host = options.host;
        this.target = options.element;
        const dialogActionsButtons = [DialogAction.OK, DialogAction.Cancel];

        const sectionDiv = document.createElement("div");

        const span = document.createElement("span");
        span.id = "datePicker";

        let button = document.createElement("button");
        button.id = "DateButton";
        button.innerText = "Date";

        button.onclick = (event) => {
            const initialDialogState = { startDate: new Date() };
            const position = {
                    type: VisualDialogPositionType.RelativeToVisual,
                    left: 100,
                    top: 30
            };

            const size = {width: 250, height: 300};
            const dialogOptions = {
                actionButtons: dialogActionsButtons,
                size: size,
                position: position,
                title: "Select a date"
            };
            this.host.openModalDialog(DatePickerDialog.id, dialogOptions, initialDialogState).
                then(ret => this.handleDialogResult(ret, span)).
                catch(error => this.handleDialogError(error, span));
        }
        sectionDiv.appendChild(button);
        sectionDiv.appendChild(span);
        this.target.appendChild(sectionDiv)
    }

    // Custom logic to handle dialog results
    private handleDialogResult( result: ModalDialogResult, targetElement: HTMLElement){
        if ( result.actionId === DialogAction.OK || result.actionId === DialogAction.Close) {
            const resultState = <DatePickerDialogResult> result.resultState;
            const selectedDate = new Date(resultState.date);
            targetElement.textContent = selectedDate.toDateString();
        }
    }

    // Custom logic to handle errors in dialog
    private handleDialogError( error: any, targetElement: HTMLElement ) {
        targetElement.textContent = "Error: " + JSON.stringify(error);
    }
}

Definiëren hoe u het dialoogvenster sluit

De voorkeursmethode voor het sluiten van het dialoogvenster is door de eindgebruiker te klikken op de knop [x], een van de actieknoppen of de achtergrond van het rapport.

U kunt het dialoogvenster ook zo programmeren dat het automatisch wordt gesloten door de IDialogHost methode Sluiten aan te roepen. Deze methode wordt vijf seconden geblokkeerd nadat het dialoogvenster is geopend, zodat de vroegste u het dialoogvenster automatisch kunt sluiten vijf seconden nadat het is gestart.

Dialoogvenster Niet weergeven

Het dialoogvenster wordt weergegeven met een selectievakje waarmee de gebruiker dialoogvensters kan blokkeren.

Dit selectievakje is een beveiligingsfunctie waarmee wordt voorkomen dat de visual modale dialoogvensters maakt (opzettelijk of niet) zonder toestemming van de gebruiker.

Deze blokkering is alleen van kracht voor de huidige sessie. Dus als een gebruiker de modale cv-dialoogvensters blokkeert, maar later van gedachten verandert, kunnen ze de dialoogvensters opnieuw inschakelen. Hiervoor moeten ze een nieuwe sessie starten (vernieuw de pagina met rapporten in Power BI-service of start Power BI Desktop opnieuw).

Overwegingen en beperkingen

• Vanaf powerbi-visuals-API 3.8 worden het dialoogvensterpictogram en de titel bepaald door het pictogram en de weergavenaam van de visual en kunnen ze niet worden gewijzigd.

• De groottebeperkingen van het dialoogvenster worden beschreven in de onderstaande tabel.

  Max/min.	Width	Hoogte
  Maximum	90% van de browserbreedte	90% van de browserhoogte
  Minimum	240 px	210 px

• Wanneer u de positie van het dialoogvenster definieert, kan de horizontale positie een positief of negatief geheel getal zijn, afhankelijk van welke kant van de visual u het vak wilt hebben. De verticale positie kan niet negatief zijn, omdat deze boven de visual wordt geplaatst.

• De volgende functies bieden geen ondersteuning voor het dialoogvenster Power BI-visuals:

  • Ingesloten analyses
  • Publiceren op internet
  • Dashboards

U kunt uw visual programmeren om te detecteren of de huidige omgeving het openen van een dialoogvenster toestaat door de Booleaanse waarde this.host.hostCapabilities.allowModalDialogin te schakelen.

Gerelateerde inhoud

Een aangepaste Power BI-visual publiceren

Een Power BI-staafdiagramvisual maken