Κοινή χρήση μέσω

Δημιουργία παραθύρου διαλόγου για την απεικόνισή σας Power BI

  • Άρθρο

Όταν δημιουργείτε μια απεικόνιση, μερικές φορές είναι χρήσιμο να εμφανίσετε πρόσθετες πληροφορίες στον πελάτη σε ξεχωριστό παράθυρο. Για παράδειγμα, μπορεί να θέλετε να κάνετε τα εξής:

  • Εμφάνιση πρόσθετων πληροφοριών - Όπως μια σημείωση κειμένου ή ένα βίντεο
  • Εμφάνιση παραθύρου διαλόγου δεδομένων εισόδου - Όπως ένα παράθυρο διαλόγου ημερομηνίας

Για αυτούς τους σκοπούς, μπορείτε να δημιουργήσετε ένα αναδυόμενο παράθυρο απεικόνισης παραθύρου παραθύρου που ονομάζεται παράθυρο διαλόγου σε αυτό το άρθρο.

Ζητήματα παραθύρου διαλόγου

Όταν δημιουργείτε ένα παράθυρο διαλόγου για την απεικόνισή σας, να θυμάστε ότι:

  • Κατά τη διάρκεια της ανάπτυξης, μπορείτε να καθορίσετε το μέγεθος και τη θέση του παραθύρου διαλόγου.
  • Όταν ενεργοποιείται το παράθυρο διαλόγου, το φόντο της αναφοράς είναι γκρι.
  • Η κεφαλίδα παραθύρου διαλόγου περιέχει το εικονίδιο της απεικόνισης και το εμφανιζόμενο όνομά της ως τίτλο.
  • Το παράθυρο διαλόγου μπορεί να έχει έως τρία κουμπιά ενέργειας. Μπορείτε να επιλέξετε τα κουμπιά που θα εμφανίζονται από μια δεδομένη επιλογή.
  • Το παράθυρο διαλόγου χρησιμοποιεί εμπλουτισμένο HTML iframe.
  • Ενώ εμφανίζεται το παράθυρο διαλόγου, δεν είναι δυνατή η εκτέλεση καμίας ενέργειας στην αναφορά μέχρι να απορριφθεί.
  • Ο κώδικας παραθύρου διαλόγου μπορεί να χρησιμοποιήσει εξωτερικές βιβλιοθήκες npm, όπως ακριβώς και η απεικόνιση.

Σημαντικό

Το παράθυρο διαλόγου δεν πρέπει να ενεργοποιείται αυθόρμητα. Θα πρέπει να είναι το άμεσο αποτέλεσμα μιας ενέργειας χρήστη.

Σχεδίαση παραθύρου διαλόγου για την απεικόνισή σας

Για να ρυθμίσετε τις παραμέτρους ενός παραθύρου διαλόγου, πρέπει να προσθέσετε δύο στοιχεία στον κώδικά σας:

Δημιουργία του αρχείου υλοποίησης πλαισίου διαλόγου

Συνιστούμε να δημιουργήσετε ένα αρχείο υλοποίησης για κάθε παράθυρο διαλόγου που δημιουργείτε. Τοποθετήστε τα αρχεία του παραθύρου διαλόγου στον src φάκελο:

Στιγμιότυπο οθόνης που εμφανίζει τη θέση ενός αρχείου υλοποίησης παραθύρου διαλόγου με την ονομασία DatePickerDialog.ts σε ένα έργο απεικονίσεων Power BI.

Κάθε αρχείο υλοποίησης του πλαισίου διαλόγου πρέπει να περιλαμβάνει τα ακόλουθα στοιχεία:

Δημιουργία κλάσης παραθύρου διαλόγου

Δημιουργήστε μια κλάση παραθύρου διαλόγου για το παράθυρο διαλόγου. Η initialState παράμετρος in 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[];
    }

Η παράμετρος position σάς επιτρέπει να αποφασίσετε πού θα πρέπει να ανοίξει το παράθυρο διαλόγου στην οθόνη. Μπορείτε να επιλέξετε να ανοίξετε το παράθυρο διαλόγου στο κέντρο της οθόνης ή μπορείτε να ορίσετε μια διαφορετική θέση σε σχέση με την απεικόνιση.

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

    export interface VisualDialogPosition {
        type: VisualDialogPositionType;
        left?: number;
        top?: number;
    }
  • Εάν δεν καθορίζεται κανένας τύπος, η προεπιλεγμένη συμπεριφορά είναι να ανοίξετε το παράθυρο διαλόγου στο κέντρο.
  • Η θέση δίνεται σε pixel σχετικά με την επάνω αριστερή γωνία της απεικόνισης.

Αυτό το παράδειγμα εμφανίζει ένα παράθυρο διαλόγου επιλογής ημερομηνίας 250 x 300 pixel 100 pixel προς τα αριστερά και 30 pixel κάτω από το επάνω μέρος της απεικόνισης:

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":

    • Ενσωματωμένη ανάλυση
    • Δημοσίευση στο web
    • Πίνακες εργαλείων

Μπορείτε να προγραμματίσετε την απεικόνισή σας για να διαπιστώσετε εάν το τρέχον περιβάλλον επιτρέπει το άνοιγμα ενός παραθύρου διαλόγου, επιλέγοντας τη δυαδική τιμή this.host.hostCapabilities.allowModalDialog.

Σχετικό περιεχόμενο