Инструменты для взаимодействия визуальных элементов Power BI

Средства для взаимодействия (InteractivityUtils) — это набор функций и классов, позволяющий упростить реализацию перекрестного выделения и перекрестной фильтрации.

Примечание

Обновления средств для взаимодействия визуальных элементов поддерживают только последнюю версию средств (3.x.x и более поздние версии).

Установка

  1. Чтобы установить пакет, выполните следующую команду в каталоге с текущим проектом визуального элемента Power BI.

    npm install powerbi-visuals-utils-interactivityutils --save
    
  2. Если вы используете версию 3.0 или более позднюю версию средства, установите powerbi-models для разрешения зависимостей.

    npm install powerbi-models --save
    
  3. Для работы со средствами для взаимодействия следует импортировать необходимый компонент в исходный код визуального элемента 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;

Определение интерфейса для точек данных

  1. Создайте экземпляр средств для взаимодействия и сохраните этот объект как свойство визуального элемента.

    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;
    }
    
  2. Расширьте базовый класс поведения.

    Примечание

    BaseBehavior появился в версии 5.6.x средств для взаимодействия. Если используется предыдущая версия, создайте класс поведения из примера ниже.

  3. Определите интерфейс для параметров класса поведения.

    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>;
    }
    
  4. Определите класс для visual behavior. Или расширьте класс BaseBehavior.

    Определение класса для visual behavior

    Класс отвечает за обработку clickcontextmenu событий мыши.

    Когда пользователь щелкает элементы данных, визуальный элемент вызывает обработчик выбора для выбора точек данных. Если пользователь щелкает фоновый элемент визуализации, вызывается обработчик снятия выделения.

    Класс имеет соответствующие методы:

    • 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> {
      // ...
    }
    
  5. Чтобы выполнить обработку щелчка элементов, вызовите метод on объекта выбора d3. Это также касается 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);
      });
    }
    
  6. Добавьте аналогичный обработчик для события 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();
            }
        });
    }
    
  7. Средства для взаимодействия вызывают метод 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();
      }
    
  8. Метод renderSelection отвечает за обновление состояния визуальных элементов на диаграмме. Ниже приведен пример реализации renderSelection.

    public renderSelection(hasSelection: boolean): void {
        this.options.elementsSelection.style("opacity", (category: any) => {
            if (category.selected) {
                return 0.5;
            } else {
                return 1;
            }
        });
    }
    
  9. Последним шагом является создание экземпляра 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();
        }
        // ...
      }
      

Дальнейшие действия