Подсказки по служебным программам

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

Требования

Чтобы использовать пакет, необходимо выполнить некоторые действия.

  • Node.js (мы рекомендуем использовать последнюю версию LTS)
  • npm (минимальная поддерживаемая версия — 3.0.0)
  • Пользовательский визуальный элемент, созданный PowerBI-visuals-tools

Установка

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

npm install powerbi-visuals-utils-tooltiputils --save

Эта команда устанавливает пакет и добавляет пакет в качестве зависимости в package.json файл.

Использование

В этом разделе описывается общедоступный API пакета. Вы увидите описание и несколько примеров для каждого общедоступного интерфейса пакета.

Этот пакет содержит способ создания TooltipServiceWrapper и методы, помогающие управлять действиями подсказок. В нем используются интерфейсы подсказок — ITooltipServiceWrapper, TooltipEventArgs, TooltipEnabledDataPoint.

Кроме того, в нем есть определенные методы (обработчики событий касания), связанные с разработкой мобильных приложений: touchEndEventName, touchStartEventName, usePointerEvents.

TooltipServiceWrapper предоставляет самый простой способ управления подсказками.

Этот модуль предоставляет следующие интерфейсы и функции:

createTooltipServiceWrapper

Эта функция создает экземпляр класса ITooltipServiceWrapper.

function createTooltipServiceWrapper(tooltipService: ITooltipService, rootElement: Element, handleTouchDelay?: number,  getEventMethod?: () => MouseEvent): ITooltipServiceWrapper;

ITooltipService доступен в IVisualHost.

Пример

import { createTooltipServiceWrapper } from "powerbi-visuals-utils-tooltiputils";

export class YourVisual implements IVisual {
    // implementation of IVisual.

    constructor(options: VisualConstructorOptions) {
        createTooltipServiceWrapper(
            options.host.tooltipService,
            options.element);

        // returns: an instance of ITooltipServiceWrapper.
    }
}

Пример кода пользовательского визуального элемента см. здесь.

ITooltipServiceWrapper

Этот интерфейс описывает открытые методы TooltipService

interface ITooltipServiceWrapper {
    addTooltip<T>(selection: d3.Selection<any, any, any, any>, getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => powerbi.extensibility.VisualTooltipDataItem[], getDataPointIdentity?: (args: TooltipEventArgs<T>) => powerbi.visuals.ISelectionId, reloadTooltipDataOnMouseMove?: boolean): void;
    hide(): void;
}

ITooltipServiceWrapper.addTooltip

Этот метод добавляет подсказки к текущему выбору.

addTooltip<T>(selection: d3.Selection<any>, getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[], getDataPointIdentity?: (args: TooltipEventArgs<T>) => ISelectionId, reloadTooltipDataOnMouseMove?: boolean): void;

Пример

import { createTooltipServiceWrapper, TooltipEventArgs, ITooltipServiceWrapper, TooltipEnabledDataPoint } from "powerbi-visuals-utils-tooltiputils";

let bodyElement = d3.select("body");

let element = bodyElement
    .append("div")
    .style({
        "background-color": "green",
        "width": "150px",
        "height": "150px"
    })
    .classed("visual", true)
    .data([{
        tooltipInfo: [{
            displayName: "Power BI",
            value: 2016
        }]
    }]);

let tooltipServiceWrapper: ITooltipServiceWrapper = createTooltipServiceWrapper(tooltipService, bodyElement.get(0)); // tooltipService is from the IVisualHost.

tooltipServiceWrapper.addTooltip<TooltipEnabledDataPoint>(element, (eventArgs: TooltipEventArgs<TooltipEnabledDataPoint>) => {
    return eventArgs.data.tooltipInfo;
});

// You will see a tooltip if you mouseover the element.

Пример кода пользовательского визуального элемента см. здесь.

Также обратите внимание на следующий пример настройки подсказки в пользовательском визуальном элементе на диаграмме Ганта

ITooltipServiceWrapper.hide

Этот метод скрывает подсказку.

hide(): void;

Пример

import {createTooltipServiceWrapper} from "powerbi-visuals-utils-tooltiputils";

let tooltipServiceWrapper = createTooltipServiceWrapper(options.host.tooltipService, options.element); // options are from the VisualConstructorOptions.

tooltipServiceWrapper.hide();

Interfaces

Эти интерфейсы используются при создании TooltipServiceWrapper и его использовании. Кроме того, они были упомянуты в примерах из предыдущего раздела — здесь.

TooltipEventArgs

interface TooltipEventArgs<TData> {
    data: TData;
    coordinates: number[];
    elementCoordinates: number[];
    context: HTMLElement;
    isTouchEvent: boolean;
}

TooltipEnabledDataPoint

interface TooltipEnabledDataPoint {
    tooltipInfo?: powerbi.extensibility.VisualTooltipDataItem[];
}

TooltipServiceWrapperOptions

interface TooltipServiceWrapperOptions {
    tooltipService: ITooltipService;
    rootElement: Element;
    handleTouchDelay: number;
    getEventMethod?: () => MouseEvent;

Touch events

Теперь подсказки позволяют управлять несколькими событиями касания, которые полезны для разработки мобильных приложений.

touchStartEventName

function touchStartEventName(): string

Этот метод возвращает имя события запуска касания.

touchEndEventName

function touchEndEventName(): string

Этот метод возвращает имя события запуска касания.

usePointerEvents

function usePointerEvents(): boolean

Этот метод возвращает текущее событие touchStart, связанное с указателем.