Bagikan melalui

Membuat kotak dialog untuk visual Power BI Anda

Saat Anda membuat visual, terkadang berguna untuk menampilkan informasi tambahan kepada pelanggan di jendela terpisah. Misalnya, Anda mungkin perlu:

  • Perlihatkan informasi tambahan - Seperti catatan teks atau video
  • Menampilkan kotak dialog data input - Seperti kotak dialog tanggal

Untuk tujuan ini, Anda dapat membuat jendela pop-up visual dialog, yang disebut kotak dialog di artikel ini.

Pertimbangan kotak dialog

Saat membuat kotak dialog untuk visual Anda, ingatlah bahwa:

  • Selama pengembangan, Anda dapat menentukan ukuran dan posisi kotak dialog.
  • Saat kotak dialog dipicu, latar belakang laporan berwarna abu-abu.
  • Header dialog berisi ikon visual dan nama tampilannya sebagai judul.
  • Kotak dialog dapat memiliki hingga tiga tombol tindakan. Anda dapat memilih tombol mana yang akan ditampilkan dari pilihan tertentu.
  • Kotak dialog menggunakan HTML iframe yang kaya.
  • Saat kotak dialog ditampilkan, tidak ada tindakan yang dapat dilakukan dalam laporan hingga dihentikan.
  • Kode dialog dapat menggunakan pustaka npm eksternal, sama seperti visualnya.

Penting

Kotak dialog tidak boleh dipicu secara spontan. Ini harus menjadi hasil langsung dari tindakan pengguna.

Merancang kotak dialog untuk visual Anda

Untuk mengonfigurasi kotak dialog, Anda perlu menambahkan dua komponen ke kode Anda:

Membuat file implementasi kotak dialog

Sebaiknya buat file implementasi untuk setiap kotak dialog yang Anda buat. Tempatkan file kotak dialog Anda di folder src:

Cuplikan layar memperlihatkan lokasi file implementasi kotak dialog yang disebut DatePickerDialog.ts dalam proyek visual Power BI.

Setiap file implementasi kotak dialog harus menyertakan komponen berikut:

Membuat kotak dialog

Membuat kotak dialog untuk kotak dialog Anda. Parameter initialState diteruskan openModalDialog ke kontraktor dialog setelah pembuatannya. Gunakan objek initialState untuk meneruskan parameter ke kotak dialog, untuk memengaruhi perilaku atau tampilannya.

Kode dialog dapat menggunakan metode IDialogHost ini:

  • IDialogHost.setResult(result:object) - Kode dialog mengembalikan objek hasil yang diteruskan kembali ke visual panggilannya.
  • IDialogHost.close(actionId: DialogAction, result?:object) - Kode dialog dapat secara terprogram menutup dialog dan memberikan objek hasil kembali ke visual panggilannya.

Impor di atas file:

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

Contoh ini mengharuskan untuk menginstal paket ini:

    npm i react-dom react react-datepicker

Realisasi kelas:

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

Membuat kelas hasil

Buat kelas yang mengembalikan hasil kotak dialog, lalu tambahkan ke file implementasi kotak dialog.

Dalam contoh di bawah ini, kelas DatePickerDialogResult mengembalikan string tanggal.

export class DatePickerDialogResult {
    date: string;
}

Tambahkan kotak dialog Anda ke daftar registri

Setiap file implementasi dialog perlu menyertakan referensi registri. Tambahkan dua baris dalam contoh di bawah ini ke akhir file implementasi kotak dialog Anda. Baris pertama harus identik dalam setiap file implementasi kotak dialog. Baris kedua mencantumkan kotak dialog Anda; ubah sesuai dengan nama kelas kotak dialog Anda.

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

Panggil kotak dialog

Sebelum membuat kotak dialog, Anda perlu memutuskan tombol mana yang akan disertakannya. Power BI visual mendukung enam tombol kotak dialog berikut:

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

Setiap kotak dialog yang Anda buat perlu dipanggil dalam file visual.ts. Dalam contoh ini, kotak dialog ditentukan dengan dua tombol tindakan.

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

Dalam contoh ini, kotak dialog dipanggil dengan mengeklik tombol visual. Tombol visual didefinisikan sebagai bagian dari konstruktor visual dalam file visual.ts.

Menentukan ukuran dan posisi kotak dialog

Dari API versi 4.0 atau yang lebih baru, Anda dapat menentukan ukuran dan posisi kotak dialog menggunakan DialogOpenOptions parameter openModalDialog. Untuk mengetahui versi mana yang Anda gunakan, periksa apiVersion di file pbiviz.json .

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

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

Parameter posisi memungkinkan Anda memutuskan di mana kotak dialog harus terbuka di layar. Anda dapat memilih untuk membuka kotak dialog di tengah layar, atau Anda dapat menentukan posisi yang berbeda relatif terhadap visual.

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

    export interface VisualDialogPosition {
        type: VisualDialogPositionType;
        left?: number;
        top?: number;
    }
  • Jika tidak ada jenis yang ditentukan, perilaku defaultnya adalah membuka kotak dialog di tengah.
  • Posisi diberikan dalam piksel relatif terhadap sudut kiri atas visual.

Contoh ini memperlihatkan kotak dialog pemilihan tanggal piksel 250 x 300 piksel 100 piksel di sebelah kiri dan 30 piksel di bawah bagian atas visual:

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

Tentukan cara menutup kotak dialog

Metode yang disukai untuk menutup kotak dialog adalah dengan pengguna akhir mengklik tombol [x], salah satu tombol tindakan, atau latar belakang laporan.

Anda juga dapat memprogram kotak dialog untuk menutup secara otomatis dengan memanggil IDialogHost metode tutup. Metode ini diblokir selama lima detik setelah dialog dibuka, sehingga paling cepat Anda dapat menutup kotak dialog adalah lima detik setelah dimulai secara otomatis.

Jangan perlihatkan kotak dialog

Kotak dialog muncul dengan kotak centang yang memberi pengguna opsi untuk memblokir kotak dialog.

Cuplikan layar memperlihatkan kotak centang yang memberikan opsi untuk memblokir kotak dialog.

Kotak centang ini adalah fitur keamanan yang mencegah visual membuat dialog modal (baik sengaja atau tidak) tanpa persetujuan pengguna.

Pemblokiran ini hanya berlaku untuk sesi saat ini. Jadi, jika pengguna memblokir dialog modal CV tetapi kemudian berubah pikiran, mereka dapat mengaktifkan kembali dialog. Untuk melakukannya, mereka perlu memulai sesi baru (refresh halaman laporan di layanan Power BI, atau mulai ulang Power BI Desktop).

Pertimbangan dan batasan

  • Pada powerbi-visuals-API 3.8, ikon dialog dan judul ditentukan oleh ikon visual dan nama tampilan dan tidak dapat diubah.

  • Batasan ukuran kotak dialog dijelaskan dalam tabel di bawah ini.

    Maksimal/minimal Width Height
    Maksimum 90% dari lebar browser 90% dari tinggi browser
    Minimum 240 px 210 px

  • Saat menentukan posisi kotak dialog, posisi horizontal dapat berupa bilangan bulat positif atau negatif, bergantung pada sisi visual mana yang Anda inginkan untuk kotak tersebut. Posisi vertikal tidak boleh negatif, karena ini akan menempatkannya di atas visual.

  • Fitur berikut ini tidak mendukung kotak dialog visual Power BI:

    • Analitik tertanam Power BI
    • Publikasikan ke web
    • Dashboard

Anda dapat memprogram visual Anda untuk mendeteksi apakah lingkungan saat ini memungkinkan pembukaan kotak dialog, dengan mencentang boolean this.host.hostCapabilities.allowModalDialog.

Konten terkait