Sdílet prostřednictvím

Vytvoření dialogového okna pro vizuál Power BI

  • Článek

Při vytváření vizuálu je někdy užitečné zobrazit zákazníkovi další informace v samostatném okně. Můžete například chtít:

  • Zobrazit další informace – například textová poznámka nebo video
  • Zobrazení dialogového okna vstupních dat – například dialogové okno datum

Pro tyto účely můžete vytvořit automaticky otevírané okno dialogového okna s názvem dialogové okno v tomto článku.

Důležité informace o dialogovém okně

Při vytváření dialogového okna pro vizuál mějte na paměti, že:

  • Během vývoje můžete zadat velikost a umístění dialogového okna.
  • Při aktivaci dialogového okna se pozadí sestavy zobrazí šedě.
  • Záhlaví dialogového okna obsahuje ikonu vizuálu a její zobrazovaný název jako název.
  • Dialogové okno může mít až tři tlačítka akcí. Můžete zvolit tlačítka, která se mají zobrazit z daného výběru.
  • Dialogové okno používá formátOVANÝ KÓD HTML iframe.
  • Během zobrazení dialogového okna nelze v sestavě provést žádnou akci, dokud ji nezavedete.
  • Kód dialogového okna může používat externí knihovny npm, stejně jako vizuál.

Důležité

Dialogové okno by se nemělo aktivovat spontánně. Mělo by to být okamžitý výsledek akce uživatele.

Návrh dialogového okna pro vizuál

Pokud chcete nakonfigurovat dialogové okno, musíte do kódu přidat dvě komponenty:

Vytvoření souboru implementace dialogového okna

Doporučujeme vytvořit implementační soubor pro každé dialogové okno, které vytvoříte. Umístěte soubory dialogového okna do src složky:

Snímek obrazovky znázorňující umístění souboru implementace dialogového okna s názvem DatePickerDialog.ts v projektu vizuálů Power BI

Každý soubor implementace dialogového okna by měl obsahovat následující komponenty:

Vytvoření třídy dialogového okna

Vytvořte třídu dialogového okna pro své dialogové okno. Parametr initialState je openModalDialog předán dodavateli dialogového okna při jeho vytvoření. Pomocí objektu initialState předejte parametry do dialogového okna, aby to ovlivnilo jeho chování nebo vzhled.

Kód dialogového okna může používat tyto IDialogHost metody:

  • IDialogHost.setResult(result:object) – Kód dialogového okna vrátí výsledný objekt, který se předá zpět do volajícího vizuálu.
  • IDialogHost.close(actionId: DialogAction, result?:object) – Kód dialogového okna může programově zavřít dialogové okno a poskytnout výsledný objekt zpět do volajícího vizuálu.

Importuje se nad souborem:

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 příklad vyžaduje instalaci těchto balíčků:

    npm i react-dom react react-datepicker

Realizace tříd:

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

Vytvoření třídy výsledků

Vytvořte třídu, která vrátí výsledek dialogového okna, a pak ji přidejte do souboru implementace dialogového okna.

V následujícím příkladu DatePickerDialogResult vrátí třída řetězec kalendářního data.

export class DatePickerDialogResult {
    date: string;
}

Přidání dialogového okna do seznamu registru

Každý soubor implementace dialogového okna musí obsahovat odkaz na registr. Přidejte dva řádky v následujícím příkladu na konec souboru implementace dialogového okna. První řádek by měl být v každém souboru implementace dialogového okna stejný. Druhý řádek vypíše vaše dialogové okno; upravte jej podle názvu třídy dialogového okna.

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

Vyvolání dialogového okna

Než vytvoříte dialogové okno, musíte se rozhodnout, která tlačítka budou obsahovat. Vizuály Power BI podporují následující šest tlačítek dialogového okna:

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

Každé dialogové okno, které vytvoříte, musí být vyvoláno v visual.ts souboru. V tomto příkladu je dialogové okno definováno dvěma tlačítky akcí.

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

V tomto příkladu je dialogové okno vyvoláno kliknutím na tlačítko vizuálu. Tlačítko vizuálu je definováno jako součást konstruktoru vizuálu visual.ts v souboru.

Definování velikosti a umístění dialogového okna

Z rozhraní API verze 4.0 nebo novější můžete definovat velikost a umístění dialogového okna pomocí parametru DialogOpenOptionsopenModalDialog. Pokud chcete zjistit, kterou verzi používáte, podívejte se do apiVersionsouboru pbiviz.json .

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

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

Parametr pozice umožňuje rozhodnout, kde se má dialogové okno na obrazovce otevřít. Můžete zvolit otevření dialogového okna uprostřed obrazovky nebo můžete definovat jinou pozici vzhledem k vizuálu.

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

    export interface VisualDialogPosition {
        type: VisualDialogPositionType;
        left?: number;
        top?: number;
    }
  • Pokud není zadán žádný typ, výchozím chováním je otevření dialogového okna uprostřed.
  • Pozice je uvedena v pixelech vzhledem k levému hornímu rohu vizuálu.

Tento příklad ukazuje dialogové okno pro výběr data o rozměrech 250 x 300 pixelů vlevo a 30 pixelů pod horní částí 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);
    }
}

Definování způsobu zavření dialogového okna

Upřednostňovanou metodou zavření dialogového okna je, že koncový uživatel klikne na tlačítko [x], jedno z tlačítek akcí nebo pozadí sestavy.

Dialogové okno můžete také naprogramovat tak, aby se automaticky zavřel voláním IDialogHost metody zavřít. Tato metoda je blokována po dobu pěti sekund po otevření dialogového okna, takže nejstarší můžete dialogové okno automaticky zavřít pět sekund po jeho zahájení.

Dialogové okno Nezobrazovat

Zobrazí se dialogové okno se zaškrtávacím políčky, které uživateli umožní blokovat dialogová okna.

Snímek obrazovky znázorňující zaškrtávací políčko s možností blokovat dialogová okna

Toto políčko je funkce zabezpečení, která brání vizuálu v vytváření modálních dialogů (záměrně nebo ne) bez souhlasu uživatele.

Toto blokování platí pouze pro aktuální relaci. Takže pokud uživatel zablokuje modální dialogy CV, ale později změní názor, může dialogy znovu povolit. Aby to mohli udělat, musí spustit novou relaci (aktualizovat stránku sestav v služba Power BI nebo restartovat Power BI Desktop).

Úvahy a omezení

  • Od powerbi-visuals-API 3.8 určuje ikona dialogového okna a název ikony a zobrazovaného názvu vizuálu a nedá se změnit.

  • Omezení velikosti dialogového okna jsou popsána v následující tabulce.

    Max/min Šířka Výška
    Maximum 90 % šířky prohlížeče 90 % výšky prohlížeče
    Minimum 240 px 210 px

  • Při definování pozice dialogového okna může být vodorovná pozice kladné nebo záporné celé číslo v závislosti na tom, kterou stranu vizuálu chcete mít. Svislá pozice nemůže být záporná, protože by se umístila nad vizuál.

  • Následující funkce nepodporují dialogové okno vizuálů Power BI:

    • Vložené analýzy
    • Publikování na webu
    • Řídicí panely

Vizuál můžete naprogramovat a zjistit, jestli aktuální prostředí umožňuje otevření dialogového okna zaškrtnutím logické hodnoty this.host.hostCapabilities.allowModalDialog.

Související obsah

Publikování vlastního vizuálu Power BI

Vytvoření vizuálu pruhového grafu Power BI