Vytvorenie dialógového okna pre vizuál služby Power BI

Keď vytvoríte vizuál, niekedy je užitočné zobraziť zákazníkovi dodatočné informácie v samostatnom okne. Možno budete chcieť napríklad vykonať:

• Zobrazenie ďalších informácií – napríklad textová poznámka alebo video
• Dialógové okno na zobrazenie vstupných údajov – napríklad dialógové okno dátumu

Na tieto účely môžete vytvoriť kontextové okno vizuálu dialógového okna s názvom dialógové okno v tomto článku.

Dôležité informácie týkajúce sa dialógového okna

Pri vytváraní dialógového okna pre vizuál nezabudnite, že:

• Počas vývoja môžete určiť veľkosť a umiestnenie dialógového okna.
• Po spustení dialógového okna je pozadie zostavy sivé.
• Hlavička dialógového okna obsahuje ikonu vizuálu a jeho zobrazovaný názov ako názov.
• Dialógové okno môže obsahovať až tri tlačidlá akcií. Z daného výberu môžete vybrať tlačidlá, ktoré sa majú zobraziť.
• Dialógové okno používa formát HTML formátu HTML iframe.
• Kým sa zobrazí dialógové okno, v zostave sa nemôže vykonať žiadna akcia, kým sa nezruší.
• Kód dialógového okna môže používať externé knižnice npm, rovnako ako vizuál.

Dôležité

Dialógové okno by nemalo byť aktivované voliteľne. Mala by to byť okamžitý výsledok akcie používateľa.

Vytvorenie dialógového okna pre vizuál

Ak chcete nakonfigurovať dialógové okno, musíte do kódu pridať dve súčasti:

• Súbor implementácie – najlepšie je vytvoriť súbor implementácie pre každé dialógové okno.
• Kód, ktorý sa má vyvolať v dialógovom okne – Ak chcete vyvolať dialógové okno, pridajte do visual.ts súboru kód.

Vytvorenie súboru implementácie dialógového okna

Odporúčame vytvoriť súbor implementácie pre každé dialógové okno, ktoré vytvoríte. Umiestnite súbory dialógového okna do src priečinka:

Každý súbor implementácie dialógového okna by mal obsahovať nasledujúce súčasti:

• Trieda dialógového okna
• Výsledná trieda
• Registrácia triedy dialógového okna

Vytvorenie triedy dialógového okna

Vytvorte triedu dialógového okna pre dialógové okno. Parameter initialState in openModalDialog sa po vytvorení odovzdá dodávateľovi dialógového okna. initialState Pomocou objektu odovzdajte parametre do dialógového okna, aby sa ovplyvnilo jeho správanie alebo vzhľad.

Kód dialógového okna môže používať tieto IDialogHost metódy:

• IDialogHost.setResult(result:object) – Kód dialógového okna vráti výsledný objekt, ktorý sa odovzdá späť do jeho volajúceho vizuálu.
• IDialogHost.close(actionId: DialogAction, result?:object) – Kód dialógového okna môže programovo zavrieť dialógové okno a poskytnúť výsledný objekt späť do volajúceho vizuálu.

Importuje nad súbor:

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

Tento príklad vyžaduje inštaláciu týchto balíkov:

    npm i react-dom react react-datepicker

Uskutočnenie triedy:

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

Vytvorenie výslednej triedy

Vytvorte triedu, ktorá vráti výsledok dialógového okna, a potom ju pridajte do súboru implementácie dialógového okna.

V nižšie uvedenom príklade DatePickerDialogResult trieda vráti reťazec dátumu.

export class DatePickerDialogResult {
    date: string;
}

Pridanie dialógového okna do zoznamu databázy Registry

Každý súbor implementácie dialógového okna musí obsahovať odkaz na databázu Registry. Pridajte dva riadky v príklade nižšie na koniec súboru implementácie dialógového okna. Prvý riadok by mal byť rovnaký v každom súbore implementácie dialógového okna. Druhý riadok obsahuje zoznam dialógových okien. upravte ho podľa názvu triedy dialógového okna.

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

Vyvolanie dialógového okna

Pred vytvorením dialógového okna sa musíte rozhodnúť, ktoré tlačidlá bude obsahovať. Vizuály Power BI podporujú nasledujúcich šesť tlačidiel dialógového okna:

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

V súbore je potrebné vyvolať visual.ts každé dialógové okno, ktoré vytvoríte. V tomto príklade je dialógové okno definované dvoma tlačidlami akcie.

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

V tomto príklade sa dialógové okno vyvolá kliknutím na tlačidlo vizuálu. Tlačidlo vizuálu je definované ako súčasť konštruktora vizuálu v súbore visual.ts .

Definovanie veľkosti a umiestnenia dialógového okna

Od rozhrania API verzie 4.0 alebo novšej môžete definovať veľkosť a polohu dialógového okna pomocou DialogOpenOptions parametra openModalDialog. Ak chcete zistiť, ktorú verziu používate, pozrite si apiVersion pbiviz.json súbore.

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

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

Parameter Pozícia vám umožňuje rozhodnúť sa, kde by sa malo dialógové okno otvoriť na obrazovke. Môžete si vybrať, či chcete otvoriť dialógové okno v strede obrazovky, alebo môžete definovať inú polohu vzhľadom na vizuál.

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

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

• Ak nie je zadaný žiadny typ, predvoleným správaním je otvoriť dialógové okno v strede.
• Pozícia je zadaná v pixeloch vzhľadom na ľavý horný roh vizuálu.

Tento príklad znázorňuje dialógové okno výberu dátumu 250 x 300 pixelov vľavo a 30 pixelov pod horným oknom vizuálu:

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

Definovanie spôsobu zavretia dialógového okna

Preferovaná metóda na zatvorenie dialógového okna je tým, že koncový používateľ klikne na tlačidlo [x], niektorého z tlačidiel akcií alebo pozadia zostavy.

Dialógové okno môžete tiež automaticky zavrieť pomocou metódy zavrienia IDialogHost . Táto metóda je blokovaná päť sekúnd po otvorení dialógového okna, takže najskoršie môžete automaticky zavrieť dialógové okno päť sekúnd po spustení.

Dialógové okno Nezobzorovať

Dialógové okno sa zobrazí so začiarkavacím políčkom, ktoré používateľovi umožňuje zablokovať dialógové okná.

Toto začiarkavacie políčko je funkcia zabezpečenia, ktorá bráni vizuálu vo vytváraní modálnych dialógových okien (buď úmyselne alebo nie) bez súhlasu používateľa.

Toto blokovanie sa prejaví iba pre aktuálnu reláciu. Ak teda používateľ zablokuje modálne dialógové okná životopisu, ale neskôr zmení názor, môže tieto dialógové okná znova povoliť. Musia na to spustiť novú reláciu (obnoviť stránku zostáv v služba Power BI alebo reštartovať Power BI Desktop).

Dôležité informácie a obmedzenia

• V prípade powerbi-visuals-API 3.8 sú ikony dialógového okna a názov určované ikonou a zobrazovaným názvom vizuálu a nemožno ich zmeniť.

• Obmedzenia veľkosti dialógového okna sú popísané v tabuľke nižšie.

  Maximum/min	Šírka	Výška
  Maximálne	90 % šírky prehliadača	90 % výšky prehliadača
  Minimum	240 px	210 px

• Pri definovaní polohy dialógového okna môže byť vodorovná poloha kladným alebo záporným celým číslom v závislosti od toho, na ktorej strane vizuálu má byť pole. Zvislá poloha nemôže byť záporná, pretože by ju umiestnite nad vizuál.

• Nasledujúce funkcie nepodporujú dialógové okno Vizuály Power BI:

  • Vložené analýzy
  • Publikovanie na webe
  • Tabule

Svoj vizuál môžete naprogramovať tak, aby ste zistili, či aktuálne prostredie umožňuje otvorenie dialógového okna začiarknutím booleovskej hodnoty this.host.hostCapabilities.allowModalDialog.

Súvisiaci obsah

• Publikovanie vlastného vizuálu služby Power BI
• Vytvorenie vizuálu pruhového grafu v službe Power BI