Utilitários de interatividade de visuais do Power BI
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 classeBaseBehavior
.Defina uma classe para
visual behavior
A classe é responsável pelos eventos de mouse
click
econtextmenu
.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
classeimport 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 d3
on
. Isso também se aplica aelementsSelection
eclearCatcherSelection
.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étodoshowContextMenu
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étodobindEvents
: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 derenderSelection
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étodobind
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
oucategories: VisualDataPoint[];
.this.behavior
é uma nova instância devisual behavior
criada no construtor do visual, conforme mostrado:export class Visual implements IVisual { // ... constructor(options: VisualConstructorOptions) { // ... this.behavior = new Behavior(); } // ... }
Conteúdo relacionado
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de