Compartir a través de

Creación de un cuadro de diálogo para el objeto visual de Power BI

  • Artículo

Al crear un objeto visual, hay ocasiones en las que resulta útil mostrar información adicional al cliente en una ventana independiente. Por ejemplo, puedes:

  • Mostrar información adicional, por ejemplo, una nota de texto o un vídeo.
  • Mostrar un cuadro de diálogo de entrada de datos, por ejemplo, un cuadro de diálogo de fecha.

Para estos fines, puede crear una ventana de diálogo emergente de objeto visual, denominada cuadro de diálogo, en este artículo.

Consideraciones sobre el cuadro de diálogo

Al crear un cuadro de diálogo para el objeto visual, tenga en cuenta lo siguiente:

  • Durante el desarrollo, puede especificar el tamaño y la posición del cuadro de diálogo.
  • Cuando se desencadena el cuadro de diálogo, el fondo del informe se muestra atenuado.
  • El encabezado del cuadro de diálogo contendrá el icono del objeto visual y su nombre para mostrar como título.
  • El cuadro de diálogo puede tener hasta tres botones de acción. Puede elegir qué botones mostrar de una selección determinada.
  • El cuadro de diálogo usa un elemento iframe de HTML enriquecido.
  • Mientras se muestra el cuadro de diálogo, no se puede realizar ninguna acción en el informe hasta que se descarte.
  • El código del cuadro de diálogo puede usar bibliotecas npm externas, igual que el objeto visual.

Importante

El cuadro de diálogo no se debe desencadenar de forma espontánea. Debe ser el resultado inmediato de una acción del usuario.

Diseño de un cuadro de diálogo para el objeto visual

Para configurar un cuadro de diálogo, debe agregar dos componentes al código:

Creación del archivo de implementación del cuadro de diálogo

Se recomienda crear un archivo de implementación para cada cuadro de diálogo que se genere. Coloque los archivos del cuadro de diálogo en la carpeta src:

Captura de pantalla que muestra la ubicación de un archivo de implementación de cuadro de diálogo denominado DatePickerDialog.ts en un proyecto de objetos visuales de Power BI.

Cada archivo de implementación del cuadro de diálogo debe incluir los componentes siguientes:

Creación de una clase de cuadro de diálogo

Cree una clase de cuadro de diálogo para el mismo. El parámetro initialState de openModalDialog se pasa al contratista del cuadro de diálogo tras su creación. Use el objeto initialState para pasar parámetros al cuadro de diálogo y, de este modo, que afecte a su comportamiento o apariencia.

El código del cuadro de diálogo puede usar estos métodos IDialogHost:

  • IDialogHost.setResult(result:object): el código del cuadro de diálogo devuelve un objeto de resultado que volverá al objeto visual que realiza la llamada.
  • IDialogHost.close(actionId: DialogAction, result?:object): el código del cuadro de diálogo puede cerrar dicho cuadro mediante programación y facilitar de vuelta un objeto de resultado al objeto visual que realiza la llamada.

Importa en la parte superior del archivo:

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

Este ejemplo requiere instalar estos paquetes:

    npm i react-dom react react-datepicker

Realización de clases:

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

Creación de una clase de resultado

Cree una clase que devuelva el resultado del cuadro de diálogo y agréguelo al archivo de implementación del cuadro de diálogo.

En el ejemplo siguiente, la clase DatePickerDialogResult devuelve una cadena de fecha.

export class DatePickerDialogResult {
    date: string;
}

Incorporación del cuadro de diálogo a la lista del registro

Cada archivo de implementación del cuadro de diálogo debe incluir una referencia del registro. Agregue las dos líneas del ejemplo siguiente al final del archivo de implementación del cuadro de diálogo. La primera línea debe ser idéntica en cada archivo de implementación del cuadro de diálogo. En la segunda línea se muestra el cuadro de diálogo y se modifica según el nombre de la clase del cuadro de diálogo.

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

Invocación del cuadro de diálogo

Antes de crear un cuadro de diálogo, debe decidir qué botones incluirá. Los objetos visuales de Power BI admiten los seis botones de cuadro de diálogo siguientes:

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

Cada cuadro de diálogo que cree debe invocarse en el archivo visual.ts. En este ejemplo, el cuadro de diálogo se define con dos botones de acción.

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

En este ejemplo, el cuadro de diálogo se invoca haciendo clic en un botón visual. El botón del objeto visual se define como parte del constructor del objeto visual en el archivo visual.ts.

Definición del tamaño y la posición del cuadro de diálogo

A partir de la versión 4.0 de la API, puede definir el tamaño y la posición del cuadro de diálogo con el parámetro DialogOpenOptions de openModalDialog. Para averiguar qué versión usa, compruebe apiVersion en el archivo pbiviz.json.

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

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

El parámetro position permite decidir dónde se debe abrir el cuadro de diálogo en la pantalla. Puede elegir abrir el cuadro de diálogo en el centro de la pantalla o puede definir una posición diferente con respecto al objeto visual.

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

    export interface VisualDialogPosition {
        type: VisualDialogPositionType;
        left?: number;
        top?: number;
    }
  • Si no se especifica ningún tipo, el comportamiento predeterminado es abrir el cuadro de diálogo en el centro.
  • La posición se proporciona en píxeles con respecto a la esquina superior izquierda del objeto visual.

En este ejemplo se muestra un cuadro de diálogo de selección de fecha de 250 x 300 píxeles, a 100 píxeles a la izquierda y 30 píxeles por debajo de la parte superior del objeto 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);
    }
}

Procedimientos para cerrar el cuadro de diálogo

El método de preferencia para cerrar el cuadro de diálogo es que el usuario final haga clic en el botón [x], en uno de los botones de acción o en el fondo del informe.

También se puede programar el cuadro de diálogo para que se cierre automáticamente; para ello, llame al método de cierre IDialogHost. Este método se bloquea durante cinco segundos después de abrir el cuadro de diálogo, de modo que lo más pronto que lo puede cerrar automáticamente es cinco segundos después de que se inicie.

No mostrar el cuadro de diálogo

El cuadro de diálogo aparece con una casilla que ofrece al usuario la opción de bloquear cuadros de diálogo.

Captura de pantalla que muestra una casilla que ofrece la opción de bloquear cuadros de diálogo.

Esta casilla es una característica de seguridad que impide que el objeto visual cree cuadros de diálogo modales (ya sea intencionadamente o no) sin el consentimiento del usuario.

Este bloqueo es efectivo solo en la sesión actual. De esta forma, si un usuario bloquea los diálogos modales de CV, pero más adelante cambia de opinión, puede volver a habilitar los diálogos. Para ello, debe iniciar una nueva sesión (actualizar la página de informes en servicio Power BI o reiniciar Power BI Desktop).

Consideraciones y limitaciones

  • A partir de powerbi-visuals-API 3.8, el icono y el título del cuadro de diálogo están determinados por el icono y el nombre para mostrar del objeto visual y no se pueden cambiar.

  • En la tabla siguiente se describen las limitaciones de tamaño del cuadro de diálogo.

    Máx./mín. Ancho Alto
    Máximo 90 % del ancho del explorador 90 % del alto del explorador
    Mínima 240 px 210 px

  • Al definir la posición del cuadro de diálogo, la posición horizontal puede ser un entero positivo o negativo, en función del lado del objeto visual en el que quiera colocar el cuadro. La posición vertical no puede ser negativa, ya que lo colocaría encima del objeto visual.

  • Las características siguientes no admiten el cuadro de diálogo de objetos visuales de Power BI:

    • Análisis insertados
    • Publicar en Web
    • Paneles

Puede programar el objeto visual para detectar si el entorno actual permite abrir un cuadro de diálogo. Para ello, compruebe el valor booleano this.host.hostCapabilities.allowModalDialog.

Contenido relacionado