สร้างกล่องโต้ตอบสําหรับวิชวล Power BI ของคุณ

เมื่อคุณสร้างวิชวล บางครั้งก็มีประโยชน์ในการแสดงข้อมูลเพิ่มเติมให้ลูกค้าในหน้าต่างแยกต่างหาก ตัวอย่างเช่น คุณอาจต้องการ:

• แสดงข้อมูลเพิ่มเติม - เช่น บันทึกย่อข้อความหรือวิดีโอ
• แสดงกล่องโต้ตอบ ข้อมูลป้อนเข้า - เช่น กล่องโต้ตอบวันที่

สําหรับวัตถุประสงค์เหล่านี้ คุณสามารถสร้างหน้าต่างแบบป็อปอัพวิชวลกล่องโต้ตอบ ที่เรียกว่า กล่องโต้ตอบ ในบทความนี้

ข้อควรพิจารณาของกล่องโต้ตอบ

เมื่อสร้างกล่องโต้ตอบสําหรับวิชวลของคุณ ให้จําไว้ว่า:

• ในระหว่างการพัฒนา คุณสามารถระบุขนาดและตําแหน่งของกล่องโต้ตอบได้
• เมื่อกล่องโต้ตอบถูกทริกเกอร์ พื้นหลังของรายงานจะเป็นสีเทา
• ส่วนหัวของกล่องโต้ตอบประกอบด้วยไอคอนของวิชวลและชื่อที่แสดงเป็นชื่อเรื่อง
• กล่องโต้ตอบสามารถมีปุ่มการดําเนินการได้สูงสุดสามปุ่ม คุณสามารถเลือกปุ่มที่จะแสดงจากส่วน ที่เลือกที่ระบุได้
• กล่องโต้ตอบใช้ HTML iframeแบบ rich
• ในขณะที่กล่องโต้ตอบแสดงขึ้น คุณจะไม่สามารถดําเนินการในรายงานได้จนกว่าจะถูกปิด
• รหัสกล่องโต้ตอบสามารถใช้ไลบรารี npm ภายนอกได้เช่นเดียวกับวิชวล

สำคัญ

ไม่ควรทริกเกอร์กล่องโต้ตอบที่เกิดขึ้นเอง ซึ่งควรเป็นผลลัพธ์ทันทีของการดําเนินการของผู้ใช้

ออกแบบกล่องโต้ตอบสําหรับวิชวลของคุณ

ในการกําหนดค่ากล่องโต้ตอบ คุณจําเป็นต้องเพิ่มคอมโพเนนต์สองส่วนลงในโค้ดของคุณ:

• ไฟล์ การใช้งาน - การสร้างไฟล์การใช้งานสําหรับแต่ละกล่องโต้ตอบเป็นแนวทางปฏิบัติที่ดีที่สุด
• โค้ดที่จะเรียกใช้กล่องโต้ตอบ ของคุณ - เมื่อต้องการเรียกกล่องโต้ตอบของคุณ ให้เพิ่มโค้ดลงใน visual.ts ไฟล์

สร้างไฟล์การใช้งานกล่องโต้ตอบ

เราขอแนะนําให้สร้างไฟล์การใช้งานสําหรับแต่ละกล่องโต้ตอบที่คุณสร้าง วางไฟล์กล่องโต้ตอบของคุณใน src โฟลเดอร์:

แต่ละไฟล์การใช้งานกล่องโต้ตอบควรมีคอมโพเนนต์ต่อไปนี้:

• คลาสของกล่องโต้ตอบ
• คลาสผลลัพธ์
• การลงทะเบียนคลาสกล่องโต้ตอบ

สร้างคลาสกล่องโต้ตอบ

สร้างคลาสกล่องโต้ตอบสําหรับกล่องโต้ตอบของคุณ พารามิเตอร์ initialState ใน openModalDialog จะถูกส่งผ่านไปยังผู้รับเหมากล่องโต้ตอบเมื่อสร้างพารามิเตอร์ initialStateใช้วัตถุเพื่อส่งผ่านพารามิเตอร์ไปยังกล่องโต้ตอบเพื่อส่งผลกระทบต่อลักษณะการทํางานหรือลักษณะของวัตถุ

รหัสกล่องโต้ตอบสามารถใช้วิธีการเหล่านี้ IDialogHost :

• IDialogHost.setResult(result:object) - รหัสกล่องโต้ตอบส่งกลับออบเจ็กต์ผลลัพธ์ที่ถูกส่งกลับไปยังวิชวลการโทร
• IDialogHost.close(actionId: DialogAction, result?:object) - รหัสกล่องโต้ตอบสามารถปิดกล่องโต้ตอบทางโปรแกรมและให้วัตถุผลลัพธ์กลับไปยังวิชวลการโทร

นําเข้าที่ด้านบนของไฟล์:

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

ตัวอย่างนี้จําเป็นต้องติดตั้งแพคเกจเหล่านี้:

    npm i react-dom react react-datepicker

การรับรู้ระดับ:

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

สร้างคลาสผลลัพธ์

สร้างคลาสที่ส่งกลับผลลัพธ์ของกล่องโต้ตอบ จากนั้นเพิ่มลงในไฟล์การใช้งานกล่องโต้ตอบ

ในตัวอย่างด้านล่าง DatePickerDialogResult คลาส จะส่งกลับสตริงวันที่

export class DatePickerDialogResult {
    date: string;
}

เพิ่มกล่องโต้ตอบของคุณลงในรายการรีจิสทรี

ไฟล์การใช้งานกล่องโต้ตอบทั้งหมดต้องมีการอ้างอิงรีจิสทรี เพิ่มสองบรรทัดในตัวอย่างด้านล่างไปยังจุดสิ้นสุดของไฟล์การใช้งานกล่องโต้ตอบของคุณ บรรทัดแรกควรเหมือนกันในทุกไฟล์การใช้งานกล่องโต้ตอบ เส้นที่สองจะแสดงรายการกล่องโต้ตอบของคุณ แต่เส้นที่สองจะแสดงรายการกล่องโต้ตอบของคุณ ปรับเปลี่ยนตามชื่อของคลาสกล่องโต้ตอบของคุณ

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

เรียกกล่องโต้ตอบ

ก่อนที่คุณจะสร้างกล่องโต้ตอบ คุณจําเป็นต้องตัดสินใจว่าจะรวมปุ่มใด วิชวล Power BI สนับสนุนปุ่มกล่องโต้ตอบหกปุ่มต่อไปนี้:

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

กล่องโต้ตอบแต่ละกล่องที่คุณสร้างจําเป็นต้องเรียกใช้ใน visual.ts ไฟล์ ในตัวอย่างนี้ กล่องโต้ตอบถูกกําหนดด้วยปุ่มการดําเนินการสองปุ่ม

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

ในตัวอย่างนี้ กล่องโต้ตอบจะถูกเรียกใช้โดยการคลิกปุ่มวิชวล ปุ่ม วิชวล ได้รับการกําหนดให้เป็นส่วนหนึ่งของคอนสตรักเตอร์วิชวลใน visual.ts ไฟล์

กําหนดขนาดและตําแหน่งของกล่องโต้ตอบ

จาก API เวอร์ชัน 4.0 หรือใหม่กว่า คุณสามารถกําหนดขนาดและตําแหน่งของกล่องโต้ตอบโดยใช้พารามิเตอร์ของDialogOpenOptions openModalDialog เมื่อต้องการตรวจสอบเวอร์ชันที่คุณกําลังใช้ ให้ตรวจสอบ apiVersion ในไฟล์ pbiviz.json

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

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

พารามิเตอร์ตําแหน่งช่วยให้คุณสามารถตัดสินใจว่ากล่องโต้ตอบควรเปิดที่ใดบนหน้าจอ คุณสามารถเลือกที่จะเปิดกล่องโต้ตอบตรงกลางของหน้าจอ หรือคุณสามารถกําหนดตําแหน่งอื่นที่สัมพันธ์กับวิชวลได้

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

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

• ถ้าไม่ได้ระบุชนิด ลักษณะการทํางานเริ่มต้นคือการเปิดกล่องโต้ตอบที่กึ่งกลาง
• ตําแหน่งจะถูกกําหนดเป็นพิกเซลเมื่อเทียบกับมุมบนซ้ายของวิชวล

ตัวอย่างนี้แสดงกล่องโต้ตอบการเลือกวันที่แบบ 250 x 300 พิกเซล ทางด้านซ้าย 100 พิกเซล และด้านล่างด้านบนของวิชวล 30 พิกเซล:

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

กําหนดวิธีการปิดกล่องโต้ตอบ

วิธีการที่ต้องการปิดกล่องโต้ตอบคือเมื่อผู้ใช้ปลายทางคลิกปุ่ม [x] หนึ่งในปุ่มการดําเนินการ หรือพื้นหลังของรายงาน

คุณยังสามารถโปรแกรมให้ปิดกล่องโต้ตอบโดยอัตโนมัติโดย IDialogHost การเรียกวิธีการปิด วิธีนี้จะถูกบล็อกเป็นเวลาห้าวินาทีหลังจากเปิดกล่องโต้ตอบ เพื่อให้คุณสามารถปิดกล่องโต้ตอบแรกสุดได้โดยอัตโนมัติคือห้าวินาทีหลังจากเริ่มต้นแล้ว

ไม่แสดงกล่องโต้ตอบ

กล่องโต้ตอบจะปรากฏขึ้นพร้อมกับกล่องกาเครื่องหมายที่ให้ตัวเลือกแก่ผู้ใช้ในการบล็อกกล่องโต้ตอบ

กล่องกาเครื่องหมายนี้เป็นคุณลักษณะความปลอดภัยที่ป้องกันไม่ให้วิชวลสร้างกล่องโต้ตอบแบบโมดอล (จงใจหรือไม่) โดยไม่ได้รับความยินยอมจากผู้ใช้

การบล็อกนี้จะมีผลเฉพาะสําหรับเซสชันปัจจุบันเท่านั้น ดังนั้นถ้าผู้ใช้บล็อกกล่องโต้ตอบโมดอล CV แต่หลังจากนั้นมีการเปลี่ยนแปลงใจพวกเขาสามารถเปิดใช้งานกล่องโต้ตอบได้อีกครั้ง เมื่อต้องการทําเช่นนั้น พวกเขาจําเป็นต้องเริ่มต้นเซสชันใหม่ (รีเฟรชหน้ารายงานในบริการของ Power BI หรือรีสตาร์ท Power BI Desktop)

ข้อควรพิจารณาและข้อจำกัด

• สําหรับ powerbi-visuals-API 3.8 ไอคอนกล่องโต้ตอบและชื่อเรื่องจะถูกกําหนดโดยไอคอนและชื่อที่แสดงของวิชวล และไม่สามารถเปลี่ยนแปลงได้

• ข้อจํากัดของขนาดของกล่องโต้ตอบจะอธิบายไว้ในตารางด้านล่าง

  สูงสุด/ต่ําสุด	ความกว้าง	ความสูง
  ค่าสูงสุด	90% ของความกว้างเบราว์เซอร์	90% ของความสูงของเบราว์เซอร์
  ต่ำสุด	240 px	210 px

• เมื่อกําหนดตําแหน่งของกล่องโต้ตอบ ตําแหน่งแนวนอนสามารถเป็นจํานวนเต็มบวกหรือลบ ทั้งนี้ขึ้นอยู่กับด้านของวิชวลที่คุณต้องการให้กล่องเป็น ตําแหน่งแนวตั้งไม่สามารถเป็นค่าลบได้ เนื่องจากตําแหน่งดังกล่าวอยู่เหนือวิชวล

• คุณลักษณะต่อไปนี้ไม่สนับสนุนกล่องโต้ตอบวิชวล Power BI:

  • การวิเคราะห์แบบฝังตัว
  • เผยแพร่ไปยังเว็บ
  • แดชบอร์ด

คุณสามารถโปรแกรมวิชวลของคุณให้ตรวจหาว่าสภาพแวดล้อมปัจจุบันอนุญาตให้เปิดกล่องโต้ตอบหรือไม่ โดยการตรวจสอบบูลีนthis.host.hostCapabilities.allowModalDialog

เนื้อหาที่เกี่ยวข้อง

• เผยแพร่วิชวลแบบกําหนดเองของ Power BI
• สร้างวิชวลแผนภูมิแท่ง Power BI