Power BI 視覺效果互動功能公用程式

發行項
01/10/2024

互動公用程式（ InteractivityUtils ）是一組函式和類別，可用來簡化交叉選取和交叉篩選的實作。

注意

互動功能公用程式的最新更新僅支援最新版的工具（3.x.x 和更新版本）。

安裝

若要安裝套件，請使用您目前的 Power BI 視覺效果專案，在目錄中執行下列命令。
```
npm install powerbi-visuals-utils-interactivityutils --save
```
如果您使用工具 3.0 版或更新版本，請安裝 powerbi-models 以解析相依性。
```
npm install powerbi-models --save
```
若要使用互動功能公用程式，請在 Power BI 視覺效果的原始程式碼中匯入必要的元件。
```
import { interactivitySelectionService } from "powerbi-visuals-utils-interactivityutils";
```

包含 CSS 檔案

若要搭配 Power BI 視覺效果使用套件，請將下列 CSS 檔案匯入至檔案 .less 。

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

因為 Power BI 視覺效果工具會包裝外部 CSS 規則，因此將 CSS 檔案匯入為 .less 檔案。

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

定義資料點的介面

建立互動功能公用程式的實例，並將物件儲存為視覺效果的屬性。

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已在 5.6.x 版的互動功能公用程式中引進。如果您使用舊版，請從下列範例建立行為類別。

定義行為類別選項的介面。

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

若要將函式指派給處理常式，互動功能公用程式會呼叫 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 實例，並呼叫 bind 互動 utils 實例的方法。
```
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 視覺效果互動功能公用程式

安裝

包含 CSS 檔案

SelectableDataPoint 屬性

定義資料點的介面

意見反應

意見反應

其他資源

共用方式為

Power BI 視覺效果互動功能公用程式

安裝

包含 CSS 檔案

SelectableDataPoint 屬性

定義資料點的介面

相關內容

意見反應

意見反應

其他資源