Power BI ビジュアルのインタラクティビティ ユーティリティ
インタラクティビティ ユーティリティ (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 バージョンのインタラクティビティ ユーティリティで導入されました。 以前のバージョンを使用する場合は、以下のサンプルから behavior クラスを作成してください。動作クラスのオプションのインターフェイスを定義します。
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); }); }
選択マネージャーの
showContextMenu
メソッドを呼び出すには、contextmenu
イベント用に同様のハンドラーを追加します。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
メソッドの呼び出しを作成しています。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(); } // ... }