Opret en dialogboks til din Power BI-visualisering

Når du opretter en visualisering, er det nogle gange nyttigt at vise yderligere oplysninger til kunden i et separat vindue. Det kan f.eks. være, at du vil:

• Vis yderligere oplysninger – f.eks. en tekstnote eller en video
• Vis en dialogboks med inputdata – f.eks. en datodialogboks

Til dette formål kan du oprette et pop op-vindue til dialogboksvisualisering, der kaldes en dialogboks i denne artikel.

Overvejelser i dialogboksen

Når du opretter en dialogboks til din visualisering, skal du være opmærksom på, at:

• Under udviklingen kan du angive størrelsen og placeringen af dialogboksen.
• Når dialogboksen udløses, er rapportbaggrunden nedtonet.
• Dialogboksoverskriften indeholder ikonet for visualiseringen og dets viste navn som en titel.
• Dialogboksen kan have op til tre handlingsknapper. Du kan vælge, hvilke knapper der skal vises fra en given markering.
• Dialogboksen bruger en RTF-kode iframe.
• Mens dialogboksen vises, kan der ikke udføres nogen handling i rapporten, før den er afvist.
• Dialogbokskoden kan bruge eksterne npm-biblioteker på samme måde som visualiseringen.

Vigtigt

Dialogboksen bør ikke udløses spontant. Det skal være det øjeblikkelige resultat af en brugerhandling.

Design en dialogboks til din visualisering

Hvis du vil konfigurere en dialogboks, skal du føje to komponenter til din kode:

• En implementeringsfil – Det er bedste praksis at oprette en implementeringsfil for hver dialogboks.
• Kode, der aktiverer dialogboksen – Hvis du vil aktivere dialogboksen, skal du føje kode til visual.ts filen.

Opret implementeringsfilen til dialogboksen

Vi anbefaler, at du opretter en implementeringsfil for hver dialogboks, du opretter. Placer dine dialogboksfiler i mappen src :

Hver dialogboksimplementeringsfil skal indeholde følgende komponenter:

• En dialogboksklasse
• En resultatklasse
• Registrering af dialogklassen

Opret en dialogboksklasse

Opret en dialogboksklasse til dialogboksen. Parameteren initialState i openModalDialog overføres til dialogentreprenøren, når den oprettes. Brug objektet initialState til at overføre parametre til dialogboksen for at påvirke funktionsmåden eller udseendet.

Dialogbokskoden kan bruge følgende IDialogHost metoder:

• IDialogHost.setResult(result:object) – Dialogbokskoden returnerer et resultatobjekt, der sendes tilbage til den kaldende visualisering.
• IDialogHost.close(actionId: DialogAction, result?:object) – Dialogbokskoden kan lukke dialogboksen programmatisk og levere et resultatobjekt tilbage til den kaldende visualisering.

Importerer oven på filen:

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

Dette eksempel kræver, at du installerer disse pakker:

    npm i react-dom react react-datepicker

Klasserealisering:

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});
            }
        });
    }
}

Opret en resultatklasse

Opret en klasse, der returnerer resultatet af dialogboksen, og føj den derefter til dialogboksens implementeringsfil.

I eksemplet nedenfor DatePickerDialogResult returnerer klassen en datostreng.

export class DatePickerDialogResult {
    date: string;
}

Føj dialogboksen til registreringsdatabaselisten

Alle dialogboksimplementeringsfiler skal indeholde en reference i registreringsdatabasen. Tilføj de to linjer i eksemplet nedenfor til slutningen af implementeringsfilen for dialogboksen. Den første linje skal være identisk i alle dialogboksimplementeringsfiler. I den anden linje vises dialogboksen. ændre den i henhold til navnet på din dialogboksklasse.

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

Aktivér dialogboksen

Før du opretter en dialogboks, skal du beslutte, hvilke knapper den skal indeholde. Power BI-visualiseringer understøtter følgende seks dialogboksknapper:

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

Hver dialogboks, du opretter, skal aktiveres i visual.ts filen. I dette eksempel er dialogboksen defineret med to handlingsknapper.

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

I dette eksempel aktiveres dialogboksen ved at klikke på en visualiseringsknap. Visualiseringsknappen er defineret som en del af den visuelle konstruktør i visual.ts filen.

Definer størrelsen og placeringen af dialogboksen

Fra API version 4.0 eller nyere kan du definere størrelsen og placeringen af dialogboksen ved hjælp af DialogOpenOptions parameteren for openModalDialog. Hvis du vil finde ud af, hvilken version du bruger, skal du se apiVersion i filen pbiviz.json .

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

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

Med positionsparameteren kan du bestemme, hvor dialogboksen skal åbnes på skærmen. Du kan vælge at åbne dialogboksen midt på skærmen, eller du kan definere en anden placering i forhold til visualiseringen.

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

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

• Hvis der ikke er angivet en type, er standardfunktionsmåden at åbne dialogboksen i midten.
• Placeringen angives i pixel i forhold til det øverste venstre hjørne af visualiseringen.

I dette eksempel vises en dialogboks med datovalg på 250 x 300 pixel 100 pixel til venstre og 30 pixel under toppen af visualiseringen:

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);
    }
}

Definer, hvordan dialogboksen skal lukkes

Den foretrukne metode til lukning af dialogboksen er, at slutbrugeren klikker på knappen [x], en af handlingsknapperne eller rapportens baggrund.

Du kan også programmere dialogboksen til automatisk at lukke ved at kalde lukkemetoden IDialogHost . Denne metode blokeres i fem sekunder, efter at dialogboksen er åbnet, så den tidligste, du automatisk kan lukke dialogboksen, er fem sekunder efter, at den blev startet.

Vis ikke dialogboks

Dialogboksen vises med et afkrydsningsfelt, der giver brugeren mulighed for at blokere dialogbokse.

Dette afkrydsningsfelt er en sikkerhedsfunktion, der forhindrer visualiseringen i at oprette modale dialogbokse (enten bevidst eller ej) uden brugerens samtykke.

Denne blokering er kun i kraft for den aktuelle session. Så hvis en bruger blokerer cv-modale dialogbokse, men senere skifter mening, kan vedkommende aktivere dialogerne igen. Hvis de vil gøre det, skal de starte en ny session (opdatere rapportsiden i Power BI-tjeneste eller genstarte Power BI Desktop).

Overvejelser og begrænsninger

• Fra og med powerbi-visuals-API 3.8 bestemmes dialogboksens ikon og titel af visualiseringens ikon og viste navn og kan ikke ændres.

• Størrelsesbegrænsningerne i dialogboksen er beskrevet i tabellen nedenfor.

  Maks./min.	Width	Height
  Maksimum	90 % af browserbredden	90 % af browserhøjden
  Minimum	240 px	210 px

• Når du definerer placeringen af dialogboksen, kan den vandrette placering være et positivt eller negativt heltal, afhængigt af hvilken side af visualiseringen feltet skal være. Den lodrette placering kan ikke være negativ, da den ville blive placeret over visualiseringen.

• Følgende funktioner understøtter ikke dialogboksen Power BI-visualiseringer:

  • Integreret analyse
  • Publicer på internettet
  • Dashboards

Du kan programmere din visualisering til at registrere, om det aktuelle miljø tillader åbning af en dialogboks, ved at kontrollere den booleske this.host.hostCapabilities.allowModalDialog.

Relateret indhold

• Publicer en brugerdefineret Power BI-visualisering
• Opret en visualisering med et liggende søjlediagram i Power BI