Párbeszédpanel létrehozása a Power BI-vizualizációhoz

Vizualizáció létrehozásakor néha hasznos, ha további információkat jelenít meg az ügyfél számára egy külön ablakban. Előfordulhat például, hogy a következőt szeretné:

• További információk megjelenítése – például szöveges jegyzet vagy videó
• Beviteli adatok párbeszédpanelének megjelenítése – Például dátum párbeszédpanel

Ebből a célból létrehozhat egy párbeszédpanel vizualizációs előugró ablakot, amelyet párbeszédpanelnek hívunk ebben a cikkben.

Párbeszédpanelek szempontjai

Amikor párbeszédpanelt hoz létre a vizualizációhoz, tartsa szem előtt, hogy:

• A fejlesztés során megadhatja a párbeszédpanel méretét és pozícióját.
• A párbeszédpanel aktiválásakor a jelentés háttere szürkítve jelenik meg.
• A párbeszédpanel fejléce címként tartalmazza a vizualizáció ikonját és megjelenítendő nevét.
• A párbeszédpanel legfeljebb három műveletgombot tartalmazhat. Az adott kijelölésből kiválaszthatja, hogy mely gombok jelenjenek meg.
• A párbeszédpanel gazdag HTML-t iframehasznál.
• Amíg megjelenik a párbeszédpanel, a jelentés nem hajtható végre addig, amíg el nem zárja.
• A párbeszédpanel kódja a vizualizációhoz hasonlóan külső npm-kódtárakat is használhat.

Fontos

A párbeszédpanelt nem szabad spontán aktiválni. Ennek egy felhasználói művelet azonnali eredményének kell lennie.

Párbeszédpanel tervezése a vizualizációhoz

Párbeszédpanel konfigurálásához két összetevőt kell hozzáadnia a kódhoz:

• Implementációs fájl – Ajánlott implementációs fájlt létrehozni minden párbeszédpanelhez.
• Kód a párbeszédpanel meghívásához – A párbeszédpanel meghívásához adjon hozzá kódot a visual.ts fájlhoz.

A párbeszédpanel implementálási fájljának létrehozása

Javasoljuk, hogy minden létrehozott párbeszédpanelhez hozzon létre egy implementációs fájlt. Helyezze a párbeszédpanel fájljait a src mappába:

Minden párbeszédpanel implementálási fájljának tartalmaznia kell a következő összetevőket:

• Párbeszédpanel-osztály
• Eredményosztály
• A párbeszédpanel-osztály regisztrálása

Párbeszédpanel-osztály létrehozása

Hozzon létre egy párbeszédpanel-osztályt a párbeszédpanelhez. A initialState beadott openModalDialog paraméter a létrehozáskor a párbeszédpanel-alvállalkozónak lesz átadva. initialState Az objektummal paramétereket adhat át a párbeszédpanelnek, hogy hatással legyen annak viselkedésére vagy megjelenésére.

A párbeszédpanel kódja a következő IDialogHost módszereket használhatja:

• IDialogHost.setResult(result:object) – A párbeszédpanel kódja egy eredményobjektumot ad vissza a hívó vizualizációnak.
• IDialogHost.close(actionId: DialogAction, result?:object) – A párbeszédpanel kódja programozott módon bezárhatja a párbeszédpanelt, és visszaadhat egy eredményobjektumot a hívó vizualizációnak.

Importálás a fájl tetején:

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

Ehhez a példához a következő csomagokat kell telepíteni:

    npm i react-dom react react-datepicker

Osztálymegvalósítás:

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

Eredményosztály létrehozása

Hozzon létre egy osztályt, amely visszaadja a párbeszédpanel eredményét, majd adja hozzá a párbeszédpanel implementálási fájlhoz.

Az alábbi példában az DatePickerDialogResult osztály egy dátumsztringet ad vissza.

export class DatePickerDialogResult {
    date: string;
}

Párbeszédpanel hozzáadása a beállításjegyzék listájához

Minden párbeszédpanel-implementációs fájlnak tartalmaznia kell egy beállításjegyzék-hivatkozást. Adja hozzá az alábbi példában szereplő két sort a párbeszédpanel implementálási fájljának végéhez. Az első sornak minden párbeszédpanel-implementációs fájlban azonosnak kell lennie. A második sor felsorolja a párbeszédpanelt; módosíthatja a párbeszédpanel-osztály neve szerint.

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

A párbeszédpanel meghívása

Mielőtt létrehoz egy párbeszédpanelt, el kell döntenie, hogy mely gombokat fogja tartalmazni. A Power BI-vizualizációk a következő hat párbeszédpanelgombot támogatják:

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

Minden létrehozott párbeszédpanelt meg kell hívni a visual.ts fájlban. Ebben a példában a párbeszédpanel két műveletgombdal van definiálva.

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

Ebben a példában a párbeszédpanelt egy vizualizáció gombra kattintva hívjuk meg. A vizualizáció gomb a fájl vizualizációkonstruktorának visual.ts részeként van definiálva.

A párbeszédpanel méretének és pozíciójának meghatározása

Az API 4.0-s vagy újabb verziójában a párbeszédpanel méretét és pozícióját a DialogOpenOptions következő paraméterrel határozhatja openModalDialogmeg: . Ha meg szeretné tudni, hogy melyik verziót használja, ellenőrizze a apiVersion pbiviz.json fájlban.

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

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

A pozícióparaméter segítségével eldöntheti, hogy a párbeszédpanel hol nyíljon meg a képernyőn. Megnyithatja a párbeszédpanelt a képernyő közepén, vagy megadhat egy másik pozíciót a vizualizációhoz képest.

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

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

• Ha nincs megadva típus, az alapértelmezett viselkedés a párbeszédpanel középen való megnyitása.
• A pozíció képpontban van megadva a vizualizáció bal felső sarkához képest.

Ez a példa egy 250 x 300 képpontos dátumkijelölési párbeszédpanelt mutat be, amely 100 képponttal balra és 30 képponttal a vizualizáció tetején található:

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

A párbeszédpanel bezárásának meghatározása

A párbeszédpanel bezárásának elsődleges módja az, hogy a végfelhasználó az [x] gombra, az egyik műveletgombra vagy a jelentés hátterére kattint.

A párbeszédpanelt a bezárás metódus meghívásával IDialogHost is automatikusan bezárhatja. Ez a módszer a párbeszédpanel megnyitása után öt másodpercig le van tiltva, így a párbeszédpanel legkorábbi automatikus bezárása öt másodperccel a párbeszédpanel elindítása után történik.

Nem jelenik meg a párbeszédpanel

A párbeszédpanel megjelenik egy jelölőnégyzettel, amely lehetővé teszi a felhasználó számára a párbeszédpanelek blokkolását.

Ez a jelölőnégyzet egy biztonsági funkció, amely megakadályozza, hogy a vizualizáció modális párbeszédpaneleket hozzon létre (szándékosan vagy nem) a felhasználó hozzájárulása nélkül.

Ez a blokkolás csak az aktuális munkamenetre érvényes. Ha tehát egy felhasználó letiltja a CV modális párbeszédpaneleket, de később meggondolja magát, újra engedélyezheti a párbeszédpaneleket. Ehhez új munkamenetet kell indítaniuk (frissíteniük kell a jelentések lapját Power BI szolgáltatás, vagy újra kell indítaniuk a Power BI Desktopot).

Szempontok és korlátozások

• A powerbi-visuals-API 3.8-as verziójában a párbeszédpanel ikonját és címét a vizualizáció ikonja és megjelenítendő neve határozza meg, és nem módosítható.

• A párbeszédpanel méretkorlátozásait az alábbi táblázat ismerteti.

  Max/perc	Szélesség	Magasság
  Maximum	A böngésző szélességének 90%-a	A böngésző magasságának 90%-a
  Minimum	240 px	210 px

• A párbeszédpanel pozíciójának meghatározásakor a vízszintes pozíció lehet pozitív vagy negatív egész szám attól függően, hogy a vizualizáció melyik oldalát szeretné használni. A függőleges pozíció nem lehet negatív, mivel ez a vizualizáció fölé helyezné.

• Az alábbi funkciók nem támogatják a Power BI-vizualizációk párbeszédpanelt:

  • Beágyazott elemzések
  • Webes közzététel
  • Irányítópultok

A vizualizációt úgy programozza be, hogy észlelje, hogy az aktuális környezet engedélyezi-e a párbeszédpanel megnyitását a logikai this.host.hostCapabilities.allowModalDialogérték ellenőrzésével.

Kapcsolódó tartalom

• Egyéni Power BI-vizualizáció közzététele
• Power BI-sávdiagram-vizualizáció létrehozása