Interaktivitätshilfsprogramme für Power BI-Visuals
Interaktivitätshilfsprogramme (InteractivityUtils
) bestehen aus einer Reihe von Funktionen und Klassen, die für die Vereinfachung der Implementierung für die übergreifende Auswahl und Kreuzfilterung verwendet werden können.
Hinweis
Die neuesten Updates der Interaktivitätshilfsprogramme unterstützen nur die neueste Toolversion (ab 3.x.x).
Installation
Führen Sie den folgenden Befehl im Verzeichnis mit Ihrem aktuellen Power BI-Visualprojekt aus, um das Paket zu installieren.
npm install powerbi-visuals-utils-interactivityutils --save
Wenn Sie Version 3.0 oder höher oder des Tools verwenden, installieren Sie
powerbi-models
, um Abhängigkeiten aufzulösen.npm install powerbi-models --save
Wenn Sie Interaktivitätshilfsprogramme verwenden möchten, müssen Sie die erforderliche Komponente in den Quellcode des Power BI-Visuals importieren.
import { interactivitySelectionService } from "powerbi-visuals-utils-interactivityutils";
Einschließen von CSS-Dateien
Um das Paket mit Ihrem Power BI-Visual zu verwenden, importieren Sie die folgende CSS-Datei in Ihre .less
-Datei.
node_modules/powerbi-visuals-utils-interactivityutils/lib/index.css
Importieren Sie die CSS-Datei als .less
-Datei, da das Tool für Power BI-Visuals die externen CSS-Regeln umschließt.
@import (less) "node_modules/powerbi-visuals-utils-interactivityutils/lib/index.css";
SelectableDataPoint-Eigenschaften
Normalerweise enthalten Datenpunkte Auswahlmöglichkeiten und Werte. Die Schnittstelle erweitert die SelectableDataPoint
-Schnittstelle.
SelectableDataPoint
enthält bereits folgende Eigenschaften:
/** 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;
Definieren einer Schnittstelle für Datenpunkte
Erstellen Sie eine Instanz von Interaktivitätshilfsprogrammen, und speichern Sie anschließend das Objekt als Eigenschaft des Visuals.
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; }
Erweitern Sie die Klasse mit dem Basisverhalten.
Hinweis
BaseBehavior
wurde in Version 5.6.x der Interaktivitätshilfsprogramme eingeführt. Wenn Sie eine ältere Version verwenden, erstellen Sie die Verhaltensklasse wie im nachstehenden Beispiel.Definieren Sie die Schnittstelle für Optionen der Verhaltensklasse.
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>; }
Definieren Sie eine Klasse für
visual behavior
. Oder erweitern Sie dieBaseBehavior
-Klasse.Definieren einer Klasse für
visual behavior
Die Klasse ist für die Mausereignisse
click
undcontextmenu
zuständig.Wenn ein Benutzer auf Datenelemente klickt, ruft das Visual den Auswahlhandler auf, um Datenpunkte auszuwählen. Wenn der Benutzer auf das Hintergrundelement des Visuals klickt, wird der Handler zum Löschen der Auswahl aufgerufen.
Die Klasse verfügt über die folgenden entsprechenden Methoden:
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 { // ... } }
Erweitern der Klasse
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> { // ... }
Um Klicks auf Elemente zu verarbeiten, rufen Sie die
on
-Methode des d3-Auswahlobjekts auf. Dies gilt auch fürelementsSelection
undclearCatcherSelection
.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); }); }
Fügen Sie ähnliche Handler für das
contextmenu
-Ereignis zum Aufrufen dershowContextMenu
-Methode des Auswahl-Managers hinzu.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(); } }); }
Um Handlern Funktionen zuzuweisen, rufen die Interaktivitätshilfsprogramme die
bindEvents
-Methode auf. Fügen Sie derbindEvents
-Methode die folgenden Aufrufe hinzu:bindClick
bindClearCatcher
bindContextMenu
public bindEvents( options: BaseBehaviorOptions<SelectableDataPointType>, selectionHandler: ISelectionHandler): void { this.options = options; this.selectionHandler = selectionHandler; this.bindClick(); this.bindClearCatcher(); this.bindContextMenu(); }
Die
renderSelection
-Methode wird zum Aktualisieren des Status von Visuals von Elementen im Diagramm verwendet. Eine Beispielimplementierung vonrenderSelection
finden Sie nachstehend.public renderSelection(hasSelection: boolean): void { this.options.elementsSelection.style("opacity", (category: any) => { if (category.selected) { return 0.5; } else { return 1; } }); }
Im letzten Schritt wird eine Instanz von
visual behavior
erstellt und diebind
-Methode der Instanz von Interaktivitätshilfsprogrammen aufgerufen.this.interactivity.bind(<BaseBehaviorOptions<VisualDataPoint>>{ behavior: this.behavior, dataPoints: this.categories, clearCatcherSelection: select(this.target), elementsSelection: selectionMerge });
selectionMerge
ist das d3-Auswahlobjekt, das alle auswählbaren Elemente im Visual darstellt.select(this.target)
ist das d3-Auswahlobjekt, das die DOM-Hauptelemente im Visual darstellt.this.categories
sind Datenpunkte mit Elementen, wobei die SchnittstelleVisualDataPoint
odercategories: VisualDataPoint[];
ist.this.behavior
ist eine neue Instanz vonvisual behavior
, die im Konstruktor des Visuals erstellt wird, wie gezeigt:export class Visual implements IVisual { // ... constructor(options: VisualConstructorOptions) { // ... this.behavior = new Behavior(); } // ... }