Power BI 视觉对象交互 utils

项目
12/06/2023

交互性 utils (InteractivityUtils) 是一组函数和类，可用于简化交叉选择和交叉筛选的实现。

注意

交互性 utils 的最新更新只支持最新版工具（3.x.x 及更高版本）。

安装

若要安装此包，请在当前 Power BI 视觉对象项目所在目录中运行下面的命令。
```
npm install powerbi-visuals-utils-interactivityutils --save
```
如果使用的工具是版本 3.0 或更高版本，请安装 powerbi-models 来解析依赖关系。
```
npm install powerbi-models --save
```
若要使用交互性 utils，请在 Power BI 视觉对象的源代码中导入必需组件。
```
import { interactivitySelectionService } from "powerbi-visuals-utils-interactivityutils";
```

包含 CSS 文件

若要将此包与 Power BI 视觉对象结合使用，请将下面的 CSS 文件导入 .less 文件。

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

之所以导入 CSS 文件作为 .less 文件是因为，Power BI 视觉对象工具包装外部 CSS 规则。

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

SelectableDataPoint 属性

通常，数据点包含选择和值。此接口扩展 SelectableDataPoint 接口。

SelectableDataPoint 已包含属性，如下所示：

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

定义数据点接口

创建交互性 utils 实例，然后将对象另存为视觉对象的属性。

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

扩展 BaseBehavior 类。

注意

BaseBehavior 是在 5.6.x 版本交互性 utils 中引入。如果使用的是旧版本，请通过以下示例来创建行为类。

定义行为类选项的接口。

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

为 visual behavior 定义类。或者，扩展 BaseBehavior 类。

为 visual behavior 定义类

此类负责处理 click 和 contextmenu 鼠标事件。

如果用户单击数据元素，视觉对象会调用选择处理程序来选择数据点。如果用户单击视觉对象的背景元素，则视觉对象将调用清除选择处理程序。

此类有以下对应方法：

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 {
      // ...
    }
}

扩展 BaseBehavior 类

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> {
  // ...
}

若要处理元素单击，请调用 d3 选择对象 on 方法。这也适用于 elementsSelection 和 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);
  });
}

为 contextmenu 事件添加类似的处理程序，用于调用选择管理器的 showContextMenu 方法。

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

为了将函数分配给处理程序，交互性 utils 调用 bindEvents 方法。将下面的调用添加到 bindEvents 方法中：

bindClick
bindClearCatcher
bindContextMenu

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

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

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

renderSelection 方法负责更新图表中的元素的视觉对象状态。下面是 renderSelection 的实例实现。

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

最后一步是，创建 visual behavior 实例，并调用交互性 utils 实例的 bind 方法。
```
this.interactivity.bind(<BaseBehaviorOptions<VisualDataPoint>>{
    behavior: this.behavior,
    dataPoints: this.categories,
    clearCatcherSelection: select(this.target),
    elementsSelection: selectionMerge
});
```
- selectionMerge 是 d3 选择对象，表示视觉对象的所有可选择元素。
- select(this.target) 是 d3 选择对象，表示视觉对象的主要 DOM 元素。
- this.categories 是包含元素的数据点，其中接口为 VisualDataPoint 或 categories: VisualDataPoint[];。
- this.behavior 是在视觉对象的构造函数中新建的 visual behavior 实例，如下所示：
```
export class Visual implements IVisual {
  // ...
  constructor(options: VisualConstructorOptions) {
      // ...
      this.behavior = new Behavior();
  }
  // ...
}
```

Power BI 视觉对象交互 utils

安装

包含 CSS 文件

SelectableDataPoint 属性

定义数据点接口

反馈

反馈

其他资源

Power BI 视觉对象交互 utils

安装

包含 CSS 文件

SelectableDataPoint 属性

定义数据点接口

相关内容

反馈

反馈

其他资源