InteractivityUtils

InteractivityUtils はビジュアル上のどのアイテムが選択されているかを管理する機能を提供し、これによりビジュアル韓の、クロスセレクト、クロスフィルタリングを容易にします。

クロスセレクト: 他のビジュアルで選択した内容を、カスタムビジュアルでも選択する。またはその逆。
クロスフィルター: 他のビジュアルで実施したフィルターを、カスタムビジュアルでも実施する。またはその逆。

インストール

以下手順で追加。

1. npm コマンドでインストール。powerbi-models は依存している型解決のため必要。

npm install powerbi-visuals-utils-interactivityutils --save
npm install powerbi-models --save

2. tsconfig.json の files に型情報を追加。

tsconfig.json

{
  "compilerOptions": {
  ...
  },
  "files": [
    ...,　
    "node_modules/powerbi-models/dist/models-noexports.d.ts",
    "node_modules/powerbi-visuals-utils-svgutils/lib/index.d.ts",
  ]
}

3. pbiviz.json の externalJS に追加。

pbiviz.json

{
  ...
  "externalJS": [
    ...,
    "node_modules/powerbi-visuals-utils-interactivityutils/lib/index.js"
  ],
  ...
}

4. デザインの情報を style/visual.less に追加。

visual.less

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

機能

InteractivityService - ビジュアル上のアイテムのインタラクションを管理

InteractivityService

InteractivityService はビジュアルのインタラクションに関する関数を提供。

powerbi.extensibility.utils.interactivity モジュールは以下の機能を提供:

createInteractivityService
appendClearCatcher
applySelectionStateToData
handleSelection
hasSelection
legendHasSelection

createInteractivityService

IInteractivityService インスタンスの作成

function createInteractivityService(hostServices: IVisualHost): IInteractivityService

createInteractivityService の例

import createInteractivityService = powerbi.extensibility.utils.interactivity.createInteractivityService;

export class Visual implements IVisual {
    // Implementation of IVisual

    constructor(options: VisualConstructorOptions) {
        createInteractivityService(options.host); // IInteractivityService インスタンス
    }
}

appendClearCatcher

選択解除の SVG RECT 領域を作成。

function appendClearCatcher(selection: d3.Selection<any>): d3.Selection<any>

appendClearCatcher の例

import appendClearCatcher = powerbi.extensibility.utils.interactivity.appendClearCatcher;

export class Visual implements IVisual {
    // Implementation of IVisual

    constructor(options: VisualConstructorOptions) {
        appendClearCatcher(d3.select(options.element)); 
    }
}

applySelectionStateToData

選択状態をデータポイントに反映

public applySelectionStateToData(dataPoints: SelectableDataPoint[], hasHighlights?: boolean): boolean

applySelectionStateToData の例

import SelectableDataPoint = powerbi.extensibility.utils.interactivity.SelectableDataPoint;
import IInteractivityService = powerbi.extensibility.utils.interactivity.IInteractivityService;
import createInteractivityService = powerbi.extensibility.utils.interactivity.createInteractivityService;

export class Visual implements IVisual {
    // Implementation of IVisual

    private interactivityService: IInteractivityService;

    constructor(options: VisualConstructorOptions) {
        this.interactivityService = createInteractivityService(options.host);
    }

    public update(options: VisualUpdateOptions): void {
        let dataPoints: SelectableDataPoint[] = [...];

        this.interactivityService.applySelectionStateToData(dataPoints); 
    }
}

handleSelection

アイテムが選択されたことを通知。他の項目が非選択になる。

public handleSelection(dataPoint: SelectableDataPoint, multiSelect: boolean): void

handleSelection の例

import ISelectionHandler = powerbi.extensibility.utils.interactivity.ISelectionHandler;
import SelectableDataPoint = powerbi.extensibility.utils.interactivity.SelectableDataPoint;
import IInteractiveBehavior = powerbi.extensibility.utils.interactivity.IInteractiveBehavior;

export interface YourBehaviorOptions {
    selection: d3.Selection<SelectableDataPoint>;
}

export class YourBehavior implements IInteractiveBehavior {
    // Implementation of IInteractiveBehavior

    public bindEvents(
        behaviorOptions: YourBehaviorOptions,
        selectionHandler: ISelectionHandler): void {

        const multiSelect: boolean = true;

        behaviorOptions.selection.on("click", (dataPoint: SelectableDataPoint) => {
            selectionHandler.handleSelection(subDataPoint, multiSelect); 
        });
    }
}

hasSelection

選択されたアイテムが含まれるか確認。

public hasSelection(): boolean

hasSelection の例

import IInteractivityService = powerbi.extensibility.utils.interactivity.IInteractivityService;
import createInteractivityService = powerbi.extensibility.utils.interactivity.createInteractivityService;

export class Visual implements IVisual {
    // Implementation of IVisual

    private interactivityService: IInteractivityService;

    constructor(options: VisualConstructorOptions) {
        this.interactivityService = createInteractivityService(options.host);
    }

    public update(options: VisualUpdateOptions): void {
         this.interactivityService.hasSelection(); 
    }
}

legendHasSelection

凡例で選択されたアイテムがあるか確認

public legendHasSelection(): boolean

legendHasSelection の例

import IInteractivityService = powerbi.extensibility.utils.interactivity.IInteractivityService;
import createInteractivityService = powerbi.extensibility.utils.interactivity.createInteractivityService;

export class Visual implements IVisual {
    // Implementation of IVisual

    private interactivityService: IInteractivityService;

    constructor(options: VisualConstructorOptions) {
        this.interactivityService = createInteractivityService(options.host);
    }

    public update(visualUpdateOptions: VisualUpdateOptions): void {
         this.interactivityService.legendHasSelection();     }
}

まとめ

InteractivityUtils はビジュアル上の項目の選択を容易にしますが、これだけでクロス選択やフィルターが行えるわけではありません。別の機会の詳細を紹介します。

目次へ戻る

参照

InteractivityUtils