Tworzenie okna dialogowego dla wizualizacji usługi Power BI

Podczas tworzenia wizualizacji czasami warto wyświetlić dodatkowe informacje klientowi w osobnym oknie. Na przykład możesz chcieć:

• Pokaż dodatkowe informacje — takie jak notatka tekstowa lub wideo
• Wyświetlanie okna dialogowego danych wejściowych — na przykład okno dialogowe daty

W tych celach można utworzyć okno podręczne wizualizacji okna dialogowego o nazwie okno dialogowe o nazwie okno dialogowe w tym artykule.

Zagadnienia dotyczące okna dialogowego

Podczas tworzenia okna dialogowego wizualizacji należy pamiętać, że:

• Podczas programowania można określić rozmiar i położenie okna dialogowego.
• Po wyzwoleniu okna dialogowego tło raportu jest szare.
• Nagłówek okna dialogowego zawiera ikonę wizualizacji i jej nazwę wyświetlaną jako tytuł.
• Okno dialogowe może mieć maksymalnie trzy przyciski akcji. Możesz wybrać przyciski do wyświetlenia z danego zaznaczenia.
• W oknie dialogowym jest używany bogaty kod HTML iframe.
• Gdy okno dialogowe jest wyświetlane, nie można wykonać żadnej akcji w raporcie, dopóki nie zostanie ono odrzucone.
• Kod okna dialogowego może używać zewnętrznych bibliotek npm, podobnie jak wizualizacja.

Projektowanie okna dialogowego wizualizacji

Aby skonfigurować okno dialogowe, należy dodać dwa składniki do kodu:

• Plik implementacji — najlepszym rozwiązaniem jest utworzenie pliku implementacji dla każdego okna dialogowego.
• Kod wywołujący okno dialogowe — aby wywołać okno dialogowe, dodaj kod do visual.ts pliku.

Tworzenie pliku implementacji okna dialogowego

Zalecamy utworzenie pliku implementacji dla każdego tworzonego okna dialogowego. Umieść pliki okna dialogowego w folderze src :

Każdy plik implementacji okna dialogowego powinien zawierać następujące składniki:

• Klasa okna dialogowego
• Klasa wynikowa
• Rejestracja klasy okna dialogowego

Tworzenie klasy okna dialogowego

Utwórz klasę okna dialogowego dla okna dialogowego. Parametr initialState w pliku openModalDialog jest przekazywany do wykonawcy okna dialogowego po jego utworzeniu. initialState Użyj obiektu, aby przekazać parametry do okna dialogowego, aby wpłynąć na jego zachowanie lub wygląd.

Kod okna dialogowego może używać następujących IDialogHost metod:

• IDialogHost.setResult(result:object) — Kod okna dialogowego zwraca obiekt wynikowy, który jest przekazywany z powrotem do jego wizualizacji wywołującej.
• IDialogHost.close(actionId: DialogAction, result?:object) — Kod okna dialogowego może programowo zamknąć okno dialogowe i podać obiekt wynikowy z powrotem do jego wywołującej wizualizacji.

Importuje na początku pliku:

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

W tym przykładzie wymagane jest zainstalowanie następujących pakietów:

    npm i react-dom react react-datepicker

Realizacja klasy:

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

Tworzenie klasy wynikowej

Utwórz klasę zwracającą wynik okna dialogowego, a następnie dodaj ją do pliku implementacji okna dialogowego.

W poniższym DatePickerDialogResult przykładzie klasa zwraca ciąg daty.

export class DatePickerDialogResult {
    date: string;
}

Dodawanie okna dialogowego do listy rejestru

Każdy plik implementacji okna dialogowego musi zawierać odwołanie do rejestru. Dodaj dwa wiersze w poniższym przykładzie na końcu pliku implementacji okna dialogowego. Pierwszy wiersz powinien być identyczny w każdym pliku implementacji okna dialogowego. Drugi wiersz wyświetla okno dialogowe; zmodyfikuj ją zgodnie z nazwą klasy okna dialogowego.

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

Wywoływanie okna dialogowego

Przed utworzeniem okna dialogowego należy zdecydować, które przyciski będą uwzględniane. Wizualizacje usługi Power BI obsługują następujące sześć przycisków okna dialogowego:

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

Każde utworzone okno dialogowe musi być wywoływane visual.ts w pliku. W tym przykładzie okno dialogowe jest definiowane za pomocą dwóch przycisków akcji.

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

W tym przykładzie okno dialogowe jest wywoływane przez kliknięcie przycisku wizualizacji. Przycisk wizualizacji jest definiowany jako część konstruktora wizualizacji visual.ts w pliku.

Definiowanie rozmiaru i położenia okna dialogowego

Z interfejsu API w wersji 4.0 lub nowszej można zdefiniować rozmiar i położenie okna dialogowego przy użyciu DialogOpenOptions parametru openModalDialog. Aby dowiedzieć się, której wersji używasz, sprawdź apiVersion plik pbiviz.json .

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

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

Parametr position pozwala zdecydować, gdzie powinno być otwarte okno dialogowe na ekranie. Możesz otworzyć okno dialogowe w środku ekranu lub zdefiniować inną pozycję względem wizualizacji.

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

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

• Jeśli nie określono żadnego typu, domyślne zachowanie polega na otwarciu okna dialogowego w środku.
• Pozycja jest podana w pikselach względem lewego górnego rogu wizualizacji.

W tym przykładzie pokazano okno dialogowe wyboru daty 250 x 300 pikseli po lewej stronie i 30 pikseli poniżej górnej części wizualizacji:

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

Definiowanie sposobu zamykania okna dialogowego

Preferowaną metodą zamykania okna dialogowego jest kliknięcie przez użytkownika końcowego przycisku [x], jednego z przycisków akcji lub tła raportu.

Możesz również programować okno dialogowe, aby automatycznie zamknąć, wywołując metodę IDialogHost close. Ta metoda jest blokowana przez pięć sekund po otwarciu okna dialogowego, dzięki czemu najwcześniejsze zamknięcie okna dialogowego wynosi pięć sekund po jego zainicjowaniu.

Nie pokazuj okna dialogowego

Zostanie wyświetlone okno dialogowe z polem wyboru, które daje użytkownikowi opcję blokowania okien dialogowych.

To pole wyboru to funkcja zabezpieczeń, która uniemożliwia wizualizacji tworzenie modalnych okien dialogowych (celowo lub nie) bez zgody użytkownika.

To blokowanie jest stosowane tylko dla bieżącej sesji. Jeśli więc użytkownik zablokuje modalne okna dialogowe CV, ale później zmieni zdanie, może ponownie włączyć okna dialogowe. Aby to zrobić, muszą rozpocząć nową sesję (odśwież stronę raportów w usługa Power BI lub uruchom ponownie program Power BI Desktop).

Rozważania i ograniczenia

• Od wersji powerbi-visuals-API 3.8 ikona i tytuł okna dialogowego są określane przez ikonę i nazwę wyświetlaną wizualizacji i nie można jej zmienić.

• Ograniczenia rozmiaru okna dialogowego zostały opisane w poniższej tabeli.

  Maks./min	Szerokość	Wysokość
  Maksymalnie	90% szerokości przeglądarki	90% wysokości przeglądarki
  Minimum	240 pikseli	210 pikseli

• Podczas definiowania położenia okna dialogowego położenie w poziomie może być dodatnią lub ujemną liczbą całkowitą, w zależności od tego, która strona wizualizacji ma być polem. Pozycja pionowa nie może być ujemna, ponieważ spowoduje to umieszczenie jej nad wizualizacją.

• Następujące funkcje nie obsługują okna dialogowego Wizualizacje usługi Power BI:

  • Osadzona analiza
  • Publikowanie w sieci Web
  • Pulpity nawigacyjne

Wizualizację można programować, aby wykryć, czy bieżące środowisko zezwala na otwieranie okna dialogowego, sprawdzając wartość logiczną this.host.hostCapabilities.allowModalDialog.

Powiązana zawartość

• Publikowanie wizualizacji niestandardowej usługi Power BI
• Tworzenie wizualizacji wykresu słupkowego usługi Power BI