Criar uma caixa de diálogo para o visual do Power BI

Quando você cria um visual, às vezes é útil exibir informações adicionais para o cliente em uma janela separada. Por exemplo, você pode querer:

• Mostrar informações adicionais - como uma nota de texto ou um vídeo
• Exibir uma caixa de diálogo de dados de entrada - Como uma caixa de diálogo de data

Para esses fins, você pode criar uma janela pop-up visual de diálogo, chamada de caixa de diálogo neste artigo.

Considerações sobre a caixa de diálogo

Ao criar uma caixa de diálogo para seu visual, lembre-se de que:

• Durante o desenvolvimento, você pode especificar o tamanho e a posição da caixa de diálogo.
• Quando a caixa de diálogo é acionada, o plano de fundo do relatório fica acinzentado.
• O cabeçalho da caixa de diálogo contém o ícone do visual e seu nome para exibição como um título.
• A caixa de diálogo pode ter até três botões de ação. Você pode escolher quais botões exibir a partir de uma determinada seleção.
• A caixa de diálogo usa um HTML iframeavançado .
• Enquanto a caixa de diálogo é exibida, nenhuma ação pode ser executada no relatório até que ela seja descartada.
• O código de diálogo pode usar bibliotecas npm externas, assim como o visual.

Criar uma caixa de diálogo para o seu visual

Para configurar uma caixa de diálogo, você precisa adicionar dois componentes ao seu código:

• Um arquivo de implementação - É uma prática recomendada criar um arquivo de implementação para cada caixa de diálogo.
• Código para invocar sua caixa de diálogo - Para invocar sua caixa de diálogo, adicione código ao visual.ts arquivo.

Criar o arquivo de implementação da caixa de diálogo

Recomendamos a criação de um arquivo de implementação para cada caixa de diálogo criada. Coloque os arquivos da src caixa de diálogo na pasta:

Cada arquivo de implementação da caixa de diálogo deve incluir os seguintes componentes:

• Uma classe de caixa de diálogo
• Uma classe de resultado
• Registro da classe de diálogo

Criar uma classe de caixa de diálogo

Crie uma classe de caixa de diálogo para sua caixa de diálogo. O initialState parâmetro in openModalDialog é passado para o contratante da caixa de diálogo após sua criação. Use o initialState objeto para passar parâmetros para a caixa de diálogo, a fim de afetar seu comportamento ou aparência.

O código de diálogo pode usar estes IDialogHost métodos:

• IDialogHost.setResult(result:object) - O código de diálogo retorna um objeto de resultado que é passado de volta para seu visual de chamada.
• IDialogHost.close(actionId: DialogAction, result?:object) - O código de diálogo pode programaticamente fechar a caixa de diálogo e fornecer um objeto de resultado de volta ao seu visual de chamada.

Importações no topo do ficheiro:

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 exemplo requer a instalação destes pacotes:

    npm i react-dom react react-datepicker

Realização da aula:

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

Criar uma classe de resultado

Crie uma classe que retorna o resultado da caixa de diálogo e adicione-a ao arquivo de implementação da caixa de diálogo.

No exemplo abaixo, a DatePickerDialogResult classe retorna uma cadeia de caracteres de data.

export class DatePickerDialogResult {
    date: string;
}

Adicionar sua caixa de diálogo à lista do Registro

Cada arquivo de implementação de caixa de diálogo precisa incluir uma referência do Registro. Adicione as duas linhas no exemplo abaixo ao final do arquivo de implementação da caixa de diálogo. A primeira linha deve ser idêntica em todos os arquivos de implementação da caixa de diálogo. A segunda linha lista sua caixa de diálogo; Modifique-o de acordo com o nome da sua classe de caixa de diálogo.

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

Invoque a caixa de diálogo

Antes de criar uma caixa de diálogo, você precisa decidir quais botões ela incluirá. Os visuais do Power BI suportam os seguintes seis botões de caixa de diálogo:

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

Cada caixa de diálogo criada precisa ser invocada visual.ts no arquivo. Neste exemplo, a caixa de diálogo é definida com dois botões de ação.

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

Neste exemplo, a caixa de diálogo é invocada clicando em um botão visual. O botão visual é definido como parte do construtor visual no visual.ts arquivo.

Definir o tamanho e a posição da caixa de diálogo

A partir da API versão 4.0 ou posterior, você pode definir o tamanho e a posição da caixa de diálogo usando o DialogOpenOptions parâmetro de openModalDialog. Para saber qual versão você está usando, verifique a apiVersion no arquivo pbiviz.json .

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

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

O parâmetro position permite que você decida onde a caixa de diálogo deve abrir na tela. Você pode optar por abrir a caixa de diálogo no centro da tela ou definir uma posição diferente em relação ao visual.

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

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

• Se nenhum tipo for especificado, o comportamento padrão é abrir a caixa de diálogo no centro.
• A posição é dada em pixels em relação ao canto superior esquerdo do visual.

Este exemplo mostra uma caixa de diálogo de seleção de data de 250 x 300 pixels, 100 pixels à esquerda e 30 pixels abaixo da parte superior do 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);
    }
}

Definir como fechar a caixa de diálogo

O método preferido para fechar a caixa de diálogo é o usuário final clicar no botão [x], em um dos botões de ação ou no plano de fundo do relatório.

Você também pode programar a caixa de diálogo para fechar automaticamente chamando o IDialogHost método close. Esse método é bloqueado por cinco segundos após a caixa de diálogo ser aberta, de modo que o mais cedo que você pode fechar automaticamente a caixa de diálogo é cinco segundos depois que ela foi iniciada.

Não mostrar caixa de diálogo

A caixa de diálogo aparece com uma caixa de seleção que dá ao usuário a opção de bloquear caixas de diálogo.

Esta caixa de seleção é um recurso de segurança que impede que o visual crie diálogos modais (intencionalmente ou não) sem o consentimento do usuário.

Este bloqueio está em vigor apenas para a sessão atual. Assim, se um utilizador bloquear as caixas de diálogo modais do CV, mas depois mudar de ideias, pode reativar as caixas de diálogo. Para fazer isso, eles precisam iniciar uma nova sessão (atualizar a página de relatórios no serviço do Power BI ou reiniciar o Power BI Desktop).

Considerações e limitações

• A partir do powerbi-visuals-API 3.8, o ícone e o título da caixa de diálogo são determinados pelo ícone e pelo nome de exibição do visual e não podem ser alterados.

• As limitações de tamanho da caixa de diálogo são descritas na tabela abaixo.

  Máx/min	Largura	Altura
  Máximo	90% da largura do navegador	90% da altura do navegador
  Mínimo	240 px	210 px

• Ao definir a posição da caixa de diálogo, a posição horizontal pode ser um inteiro positivo ou negativo, dependendo do lado do visual que você deseja que a caixa seja. A posição vertical não pode ser negativa, pois isso a colocaria acima do visual.

• Os seguintes recursos não oferecem suporte à caixa de diálogo Visuais do Power BI:

  • Análise incorporada
  • Publicar na Web
  • Dashboards

Você pode programar seu visual para detetar se o ambiente atual permite abrir uma caixa de diálogo, marcando o booleano this.host.hostCapabilities.allowModalDialog.

Conteúdos relacionados

• Publicar um visual personalizado do Power BI
• Criar um gráfico de barras visual do Power BI