Utilitários de interatividade de visuais do Power BI

Artigo
03/23/2023

Utilitários de interatividade (InteractivityUtils) é um conjunto de funções e classes que podem ser usadas para simplificar a implementação da seleção cruzada e da filtragem cruzada.

Observação

As atualizações mais recentes dos utilitários de interatividade dão suporte apenas à versão mais recente das ferramentas (3.x.x e posterior).

Instalação

Para instalar o pacote, execute o seguinte comando no diretório com seu projeto de visual atual do Power BI.
```
npm install powerbi-visuals-utils-interactivityutils --save
```
Se você estiver usando a versão 3.0 ou posterior da ferramenta, instale powerbi-models para resolver as dependências.
```
npm install powerbi-models --save
```
Para usar os utilitários de interatividade, importe o componente necessário no código-fonte do visual do Power BI.
```
import { interactivitySelectionService } from "powerbi-visuals-utils-interactivityutils";
```

Incluir arquivos CSS

Para usar o pacote com seu visual do Power BI, importe o seguinte arquivo CSS ao seu arquivo .less.

node_modules/powerbi-visuals-utils-interactivityutils/lib/index.css

Importe o arquivo CSS como um arquivo .less, pois a ferramenta de visuais do Power BI encapsula as regras de CSS externas.

@import (less) "node_modules/powerbi-visuals-utils-interactivityutils/lib/index.css";

Propriedades SelectableDataPoint

Geralmente, os pontos de dados contêm seleções e valores. A interface amplia a interface SelectableDataPoint.

SelectableDataPoint já contém as seguintes propriedades:

  /** Flag for identifying that a data point was selected */
  selected: boolean;

  /** Identity for identifying the selectable data point for selection purposes */
  identity: powerbi.extensibility.ISelectionId;

  /*
   * A specific identity for when data points exist at a finer granularity than
   * selection is performed.  For example, if your data points select based
   * only on series, even if they exist as category/series intersections.
   */

  specificIdentity?: powerbi.extensibility.ISelectionId;

Definir uma interface para pontos de dados

Crie uma instância de utilitários de interatividade e salve o objeto como uma propriedade do visual.

export class Visual implements IVisual {
  // ...
  private interactivity: interactivityBaseService.IInteractivityService<VisualDataPoint>;
  // ...
  constructor(options: VisualConstructorOptions) {
      // ...
      this.interactivity = interactivitySelectionService.createInteractivitySelectionService(this.host);
      // ...
  }
}

import { interactivitySelectionService } from "powerbi-visuals-utils-interactivityutils";

export interface VisualDataPoint extends interactivitySelectionService.SelectableDataPoint {
    value: powerbi.PrimitiveValue;
}

Estenda a classe de comportamento base.

Observação

BaseBehavior foi introduzido na versão 5.6.x dos utilitários de interatividade. Se você usar uma versão mais antiga, crie uma classe de comportamento a partir do exemplo a seguir.

Defina a interface para as opções de classe de comportamento.

import { SelectableDataPoint } from "./interactivitySelectionService";

import {
    IBehaviorOptions,
    BaseDataPoint
} from "./interactivityBaseService";

export interface BaseBehaviorOptions<SelectableDataPointType extends BaseDataPoint> extends IBehaviorOptions<SelectableDataPointType> {

/** d3 selection object of the main elements on the chart */
elementsSelection: Selection<any, SelectableDataPoint, any, any>;

/** d3 selection object of some elements on backgroup, to hadle click of reset selection */
clearCatcherSelection: d3.Selection<any, any, any, any>;
}

Defina uma classe para visual behavior. Ou estenda a classe BaseBehavior.

Defina uma classe para visual behavior

A classe é responsável pelos eventos de mouse click e contextmenu.

Quando um usuário clica em elementos de dados, o visual chama o manipulador de seleção para selecionar pontos de dados. Se o usuário clicar no elemento de plano de fundo do visual, ele chamará o manipulador de seleção de limpeza.

A classe tem os métodos correspondentes a seguir:

bindClick
bindClearCatcher
bindContextMenu.

export class Behavior<SelectableDataPointType extends BaseDataPoint> implements IInteractiveBehavior {

    /** d3 selection object of main elements in the chart */
    protected options: BaseBehaviorOptions<SelectableDataPointType>;
    protected selectionHandler: ISelectionHandler;

    protected bindClick() {
      // ...
    }

    protected bindClearCatcher() {
      // ...
    }

    protected bindContextMenu() {
      // ...
    }

    public bindEvents(
        options: BaseBehaviorOptions<SelectableDataPointType>,
        selectionHandler: ISelectionHandler): void {
      // ...
    }

    public renderSelection(hasSelection: boolean): void {
      // ...
    }
}

Estender a BaseBehavior classe

import powerbi from "powerbi-visuals-api";
import { interactivitySelectionService, baseBehavior } from "powerbi-visuals-utils-interactivityutils";

export interface VisualDataPoint extends interactivitySelectionService.SelectableDataPoint {
    value: powerbi.PrimitiveValue;
}

export class Behavior extends baseBehavior.BaseBehavior<VisualDataPoint> {
  // ...
}

Para lidar com um clique em elementos, chame o método de objeto de seleção d3on. Isso também se aplica a elementsSelection e clearCatcherSelection.

protected bindClick() {
  const {
      elementsSelection
  } = this.options;

  elementsSelection.on("click", (datum) => {
      const mouseEvent: MouseEvent = getEvent() as MouseEvent || window.event as MouseEvent;
      mouseEvent && this.selectionHandler.handleSelection(
          datum,
          mouseEvent.ctrlKey);
  });
}

Adicione um manipulador semelhante para o evento contextmenu, a fim de chamar o método showContextMenu do gerenciador de seleção.

protected bindContextMenu() {
    const {
        elementsSelection
    } = this.options;

    elementsSelection.on("contextmenu", (datum) => {
        const event: MouseEvent = (getEvent() as MouseEvent) || window.event as MouseEvent;
        if (event) {
            this.selectionHandler.handleContextMenu(
                datum,
                {
                    x: event.clientX,
                    y: event.clientY
                });
            event.preventDefault();
        }
    });
}

Para atribuir funções aos manipuladores, os utilitários de interatividade chamam o método bindEvents. Adicione as seguintes chamadas ao método bindEvents:

bindClick
bindClearCatcher
bindContextMenu

  public bindEvents(
      options: BaseBehaviorOptions<SelectableDataPointType>,
      selectionHandler: ISelectionHandler): void {

      this.options = options;
      this.selectionHandler = selectionHandler;

      this.bindClick();
      this.bindClearCatcher();
      this.bindContextMenu();
  }

O método renderSelection é responsável pela atualização do estado dos visuais no gráfico. Uma amostra da implementação de renderSelection pode ser encontrada a seguir.

public renderSelection(hasSelection: boolean): void {
    this.options.elementsSelection.style("opacity", (category: any) => {
        if (category.selected) {
            return 0.5;
        } else {
            return 1;
        }
    });
}

A última etapa é criar uma instância de visual behavior e chamar o método bind da instância dos utilitários de interatividade.
```
this.interactivity.bind(<BaseBehaviorOptions<VisualDataPoint>>{
    behavior: this.behavior,
    dataPoints: this.categories,
    clearCatcherSelection: select(this.target),
    elementsSelection: selectionMerge
});
```
- selectionMerge é o objeto de seleção d3, que representa todos os elementos selecionáveis no visual.
- select(this.target) é o objeto de seleção d3, que representa os elementos DOM principais do visual.
- this.categories são pontos de dados com elementos, em que a interface é VisualDataPoint ou categories: VisualDataPoint[];.
- this.behavior é uma nova instância de visual behavior criada no construtor do visual, conforme mostrado:
```
export class Visual implements IVisual {
  // ...
  constructor(options: VisualConstructorOptions) {
      // ...
      this.behavior = new Behavior();
  }
  // ...
}
```

Utilitários de interatividade de visuais do Power BI

Instalação

Incluir arquivos CSS

Propriedades SelectableDataPoint

Definir uma interface para pontos de dados

Comentários

Comentários

Recursos adicionais

Utilitários de interatividade de visuais do Power BI

Instalação

Incluir arquivos CSS

Propriedades SelectableDataPoint

Definir uma interface para pontos de dados

Conteúdo relacionado

Comentários

Comentários

Recursos adicionais