Opprette en dialogboks for Power BI-visualobjektet

Når du oppretter et visualobjekt, er det noen ganger nyttig å vise tilleggsinformasjon til kunden i et eget vindu. Det kan for eksempel hende at du vil:

• Vis tilleggsinformasjon – for eksempel en tekstmelding eller en video
• Vise en inndatadialogboks – for eksempel en datodialogboks

For slike formål kan du opprette et popup-vindu for dialogboksvisualobjekter, kalt en dialogboks i denne artikkelen.

Vurderinger i dialogboksen

Når du oppretter en dialogboks for visualobjektet, må du huske på at:

• Under utvikling kan du angi størrelsen og plasseringen til dialogboksen.
• Når dialogboksen utløses, er rapportbakgrunnen nedtonet.
• Dialogboksoverskriften inneholder ikonet for visualobjektet og visningsnavnet som en tittel.
• Dialogboksen kan ha opptil tre handlingsknapper. Du kan velge hvilke knapper som skal vises fra et gitt utvalg.
• Dialogboksen bruker en rik HTML.iframe
• Mens dialogboksen vises, kan ingen handling utføres i rapporten før den er forkastet.
• Dialogbokskoden kan bruke eksterne npm-biblioteker, akkurat som visualobjektet.

Viktig

Dialogboksen kan ikke utløses spontant. Det bør være det umiddelbare resultatet av en brukerhandling.

Utform en dialogboks for visualobjektet

Hvis du vil konfigurere en dialogboks, må du legge til to komponenter i koden:

• En implementeringsfil – Det er anbefalt fremgangsmåte å opprette en implementeringsfil for hver dialogboks.
• Kode for å aktivere dialogboksen – Hvis du vil aktivere dialogboksen, legger du til kode i visual.ts filen.

Opprette dialogboksimplementeringsfilen

Vi anbefaler at du oppretter en implementeringsfil for hver dialogboks du oppretter. Plasser dialogboksfilene src i mappen:

Hver dialogboksimplementeringsfil bør inneholde følgende komponenter:

• En dialogboksklasse
• En resultatklasse
• Registrering av dialogboksklassen

Opprette en dialogboksklasse

Opprett en dialogboksklasse for dialogboksen. Parameteren initialState sendes openModalDialog til dialogboksleverandøren ved oppretting. initialState Bruk objektet til å sende parametere til dialogboksen for å påvirke virkemåten eller utseendet.

Dialogbokskoden kan bruke disse IDialogHost metodene:

• IDialogHost.setResult(result:object) – Dialogbokskoden returnerer et resultatobjekt som sendes tilbake til kallvisualobjektet.
• IDialogHost.close(actionId: DialogAction, result?:object) – Dialogbokskoden kan programmatisk lukke dialogboksen og gi et resultatobjekt tilbake til kallvisualobjektet.

Importerer øverst i 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 eksemplet krever at du installerer disse pakkene:

    npm i react-dom react react-datepicker

Klassealisering:

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

Opprette en resultatklasse

Opprett en klasse som returnerer dialogboksresultatet, og legg den deretter til i dialogboksimplementeringsfilen.

I eksemplet nedenfor DatePickerDialogResult returnerer klassen en datostreng.

export class DatePickerDialogResult {
    date: string;
}

Legge til dialogboksen i registerlisten

Hver dialogboksimplementeringsfil må inneholde en registerreferanse. Legg til de to linjene i eksemplet nedenfor på slutten av dialogboksimplementeringsfilen. Den første linjen skal være identisk i hver dialogboksimplementeringsfil. Den andre linjen viser dialogboksen. endre den i henhold til navnet på dialogboksklassen.

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

Aktiver dialogboksen

Før du oppretter en dialogboks, må du bestemme hvilke knapper den skal inkludere. Power BI-visualobjekter støtter følgende seks dialogboksknapper:

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

Hver dialogboks du oppretter, må aktiveres i visual.ts filen. I dette eksemplet er dialogboksen definert med to handlingsknapper.

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

I dette eksemplet aktiveres dialogboksen ved å klikke en visuell knapp. Visualobjektknappen er definert som en del av den visuelle konstruktøren visual.ts i filen.

Definer størrelsen og plasseringen til dialogboksen

Fra API versjon 4.0 eller nyere kan du definere størrelsen og plasseringen til dialogboksen ved hjelp av openModalDialogparameteren DialogOpenOptions . Hvis du vil finne ut hvilken versjon du bruker, kan du se apiVersion i pbiviz.json-filen .

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

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

Med posisjonsparameteren kan du bestemme hvor dialogboksen skal åpnes på skjermen. Du kan velge å åpne dialogboksen midt på skjermen, eller du kan definere en annen posisjon i forhold til visualobjektet.

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

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

• Hvis ingen type er angitt, er standard virkemåte å åpne dialogboksen i midten.
• Plasseringen angis i piksler i forhold til øverste venstre hjørne av visualobjektet.

Dette eksemplet viser en datovalgdialogboks på 250 x 300 piksler 100 piksler til venstre og 30 piksler under toppen av visualobjektet:

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 du lukker dialogboksen

Den foretrukne metoden for å lukke dialogboksen er at sluttbrukeren klikker på [x]-knappen, en av handlingsknappene eller rapportbakgrunnen.

Du kan også programmere dialogboksen til å lukkes automatisk ved å kalle lukkingsmetoden IDialogHost . Denne metoden blokkeres i fem sekunder etter at dialogboksen er åpnet, slik at den tidligste du kan lukke dialogboksen automatisk, er fem sekunder etter at den ble startet.

Ikke vis dialogboks

Dialogboksen vises med en avmerkingsboks som gir brukeren muligheten til å blokkere dialogbokser.

Denne avmerkingsboksen er en sikkerhetsfunksjon som hindrer visualobjektet i å opprette sperrende dialogbokser (enten med vilje eller ikke) uten brukerens samtykke.

Denne blokkeringen gjelder bare for gjeldende økt. Så hvis en bruker blokkerer dialogboksene for CV-modal, men senere ombestemmer seg, kan vedkommende aktivere dialogboksene på nytt. For å gjøre dette må de starte en ny økt (oppdatere rapportsiden i Power Bi-tjeneste, eller starte Power BI Desktop på nytt).

Hensyn og begrensninger

• Fra og med powerbi-visualobjekter-API 3.8 bestemmes dialogikonet og tittelen av ikonet for visualobjektet og visningsnavnet og kan ikke endres.

• Størrelsesbegrensningene i dialogboksen er beskrevet i tabellen nedenfor.

  Maks./min	Bredde	Høyde
  Maksimalt	90 % av bredden på nettleseren	90 % av nettleserhøyden
  Minimum	240 px	210 px

• Når du definerer plasseringen av dialogboksen, kan den vannrette posisjonen være et positivt eller negativt heltall, avhengig av hvilken side av visualobjektet du vil at boksen skal være. Den loddrette posisjonen kan ikke være negativ, da dette plasserer den over visualobjektet.

• Følgende funksjoner støtter ikke dialogboksen Power BI-visualobjekter:

  • Innebygd analyse
  • Publiser på nettet
  • Instrumentbord

Du kan programmere visualobjektet til å oppdage om det gjeldende miljøet tillater åpning av en dialogboks ved å merke av for boolsk this.host.hostCapabilities.allowModalDialog.

Relatert innhold

• Publiser et egendefinert Visualobjekt i Power BI
• Opprette et visualobjekt for et Power BI-stolpediagram