Skapa en dialogruta för ditt visuella Power BI-objekt

När du skapar ett visuellt objekt är det ibland användbart att visa ytterligare information för kunden i ett separat fönster. Du kanske till exempel vill:

• Visa ytterligare information – till exempel en textanteckning eller en video
• Visa en dialogruta för indata – till exempel en datumdialogruta

För dessa ändamål kan du skapa ett popup-fönster för visuella dialogrutor som kallas för en dialogruta i den här artikeln.

Dialogruteöverväganden

Tänk på följande när du skapar en dialogruta för ditt visuella objekt:

• Under utvecklingen kan du ange dialogrutans storlek och position.
• När dialogrutan utlöses är rapportbakgrunden nedtonad.
• Dialogrubriken innehåller det visuella objektets ikon och dess visningsnamn som en rubrik.
• Dialogrutan kan ha upp till tre åtgärdsknappar. Du kan välja vilka knappar som ska visas från en viss markering.
• I dialogrutan används en omfattande HTML-kod iframe.
• Dialogrutan visas, men ingen åtgärd kan utföras i rapporten förrän den har stängts.
• Dialogkoden kan använda externa npm-bibliotek, precis som det visuella objektet.

Viktigt!

Dialogrutan ska inte utlösas spontant. Det bör vara det omedelbara resultatet av en användaråtgärd.

Utforma en dialogruta för ditt visuella objekt

Om du vill konfigurera en dialogruta måste du lägga till två komponenter i koden:

• En implementeringsfil – Det är bästa praxis att skapa en implementeringsfil för varje dialogruta.
• Kod för att anropa dialogrutan – Om du vill anropa dialogrutan lägger du till kod i visual.ts filen.

Skapa dialogrutans implementeringsfil

Vi rekommenderar att du skapar en implementeringsfil för varje dialogruta som du skapar. Placera dina dialogrutefiler i src mappen:

Varje dialogruteimplementeringsfil bör innehålla följande komponenter:

• En dialogruteklass
• En resultatklass
• Registrering av dialogklassen

Skapa en dialogruteklass

Skapa en dialogruteklass för dialogrutan. Parametern initialState i openModalDialog skickas till dialogleverantören när den skapas. Använd objektet initialState för att skicka parametrar till dialogrutan för att påverka dess beteende eller utseende.

Dialogkoden kan använda följande IDialogHost metoder:

• IDialogHost.setResult(result:object) – Dialogkoden returnerar ett resultatobjekt som skickas tillbaka till det anropande visuella objektet.
• IDialogHost.close(actionId: DialogAction, result?:object) – Dialogkoden kan programmässigt stänga dialogrutan och ange ett resultatobjekt tillbaka till det visuella objektet som anropar.

Importerar ovanpå 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';

Det här exemplet kräver att du installerar följande paket:

    npm i react-dom react react-datepicker

Klassrealisering:

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

Skapa en resultatklass

Skapa en klass som returnerar dialogruteresultatet och lägg sedan till den i dialogrutans implementeringsfil.

I exemplet nedan DatePickerDialogResult returnerar klassen en datumsträng.

export class DatePickerDialogResult {
    date: string;
}

Lägg till dialogrutan i registerlistan

Varje dialogimplementeringsfil måste innehålla en registerreferens. Lägg till de två raderna i exemplet nedan i slutet av dialogrutans implementeringsfil. Den första raden ska vara identisk i varje dialogruteimplementeringsfil. Den andra raden visar din dialogruta. ändra den enligt namnet på din dialogruteklass.

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

Anropa dialogrutan

Innan du skapar en dialogruta måste du bestämma vilka knappar den ska innehålla. Visuella Power BI-objekt stöder följande sex dialogruteknappar:

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

Varje dialogruta som du skapar måste anropas i visual.ts filen. I det här exemplet definieras dialogrutan med två åtgärdsknappar.

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

I det här exemplet anropas dialogrutan genom att klicka på en visuell knapp. Den visuella knappen definieras som en del av den visuella konstruktorn i visual.ts filen.

Definiera dialogrutans storlek och position

Från API-version 4.0 eller senare kan du definiera dialogrutans storlek och position med parametern DialogOpenOptionsopenModalDialog. Om du vill ta reda på vilken version du använder kontrollerar apiVersion du i filen pbiviz.json .

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

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

Med positionsparametern kan du bestämma var dialogrutan ska öppnas på skärmen. Du kan välja att öppna dialogrutan i mitten av skärmen, eller så kan du definiera en annan position i förhållande till det visuella objektet.

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

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

• Om ingen typ anges är standardbeteendet att öppna dialogrutan i mitten.
• Positionen anges i bildpunkter i förhållande till det övre vänstra hörnet i det visuella objektet.

I det här exemplet visas en dialogruta med datummarkeringen 250 x 300 bildpunkter 100 bildpunkter till vänster och 30 bildpunkter under det visuella objektets överkant:

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

Definiera hur du stänger dialogrutan

Den bästa metoden för att stänga dialogrutan är att slutanvändaren klickar på [x]-knappen, en av åtgärdsknapparna eller rapportens bakgrund.

Du kan också programmera dialogrutan så att den stängs automatiskt genom att anropa IDialogHost stängningsmetoden. Den här metoden blockeras i fem sekunder efter att dialogrutan har öppnats, så att det tidigaste du kan stänga dialogrutan automatiskt är fem sekunder efter att den initierades.

Visa inte dialogrutan

Dialogrutan visas med en kryssruta som ger användaren möjlighet att blockera dialogrutor.

Den här kryssrutan är en säkerhetsfunktion som förhindrar att det visuella objektet skapar modala dialogrutor (antingen avsiktligt eller inte) utan användarens medgivande.

Den här blockeringen gäller endast för den aktuella sessionen. Så om en användare blockerar cv-modaldialogrutorna men senare ändrar sig kan de återaktivera dialogrutorna. För att göra det måste de starta en ny session (uppdatera rapportsidan i Power BI-tjänst eller starta om Power BI Desktop).

Beaktanden och begränsningar

• Från och med powerbi-visuals-API 3.8 bestäms dialogikonen och rubriken av det visuella objektets ikon och visningsnamn och kan inte ändras.

• Dialogrutans storleksbegränsningar beskrivs i tabellen nedan.

  Max/min	Bredd	Höjd
  Högsta	90 % av webbläsarens bredd	90 % av webbläsarens höjd
  Minimal	240 px	210 px

• När du definierar positionen för dialogrutan kan den vågräta positionen vara ett positivt eller negativt heltal, beroende på vilken sida av det visuella objektet du vill att rutan ska vara. Den lodräta positionen kan inte vara negativ eftersom den placeras ovanför det visuella objektet.

• Följande funktioner stöder inte dialogrutan visuella Power BI-objekt:

  • Inbäddad analys
  • Publicera på webben
  • Instrumentpaneler

Du kan programmera ditt visuella objekt för att identifiera om den aktuella miljön tillåter att du öppnar en dialogruta genom att kontrollera det booleska this.host.hostCapabilities.allowModalDialog.

Relaterat innehåll

Publicera ett anpassat visuellt Power BI-objekt

Skapa ett visuellt Power BI-stapeldiagram