Utilitários de interatividade de visuais do Power BI

Artigo
01/10/2024

Interactivity utils (InteractivityUtils) é um conjunto de funções e classes que podem ser usadas para simplificar a implementação de seleção cruzada e filtragem cruzada.

Nota

As últimas atualizações de utils de interatividade suportam apenas a versão mais recente das ferramentas (3.x.x e superior).

Instalação

Para instalar o pacote, execute o seguinte comando no diretório com seu projeto 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 dependências.
```
npm install powerbi-models --save
```
Para usar utils 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 o visual do Power BI, importe o seguinte arquivo CSS para o .less arquivo.

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

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

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

Propriedades SelectableDataPoint

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

SelectableDataPoint já contém propriedades da seguinte forma:

  /** 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;

Definindo uma interface para pontos de dados

Crie uma instância de utilidades 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.

Nota

BaseBehavior foi introduzido na versão 5.6.x do Interactivity Utils. 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 BaseBehavior classe.

Definir uma classe para visual behavior

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

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 clara.

A classe tem os seguintes métodos de correspondência:

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 manipular um clique em elementos, chame o método de objeto on de seleção d3. O mesmo 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, para chamar o contextmenu método do gerente de showContextMenu 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 a manipuladores, o utils de interatividade chama o bindEvents método. Adicione as seguintes chamadas ao bindEvents método:

bindClick
bindClearCatcher
bindContextMenu

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

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

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

O renderSelection método é responsável por atualizar o estado visual dos elementos no gráfico. Um exemplo de implementação do renderSelection seguinte.

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 , e chamar o bind método da instância utils de visual behaviorinteratividade.
```
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 do visual.
- select(this.target) é o objeto de seleção d3 , que representa os principais elementos DOM do visual.
- this.categories são pontos de dados com elementos, onde a interface é VisualDataPoint ou categories: VisualDataPoint[];.
- this.behavior é uma nova instância de visual behavior created no construtor do visual, como mostrado:
```
export class Visual implements IVisual {
  // ...
  constructor(options: VisualConstructorOptions) {
      // ...
      this.behavior = new Behavior();
  }
  // ...
}
```

Partilhar via

Utilitários de interatividade de visuais do Power BI

Instalação

Incluir arquivos CSS

Propriedades SelectableDataPoint

Definindo uma interface para pontos de dados

Comentários

Recursos adicionais

Partilhar via

Utilitários de interatividade de visuais do Power BI

Instalação

Incluir arquivos CSS

Propriedades SelectableDataPoint

Definindo uma interface para pontos de dados

Conteúdos relacionados

Comentários

Recursos adicionais