Power BI 视觉对象交互 utils
交互性 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(); } // ... }