通过

工具提示 Utils

  • 项目

本文介绍了如何安装、导入和使用工具提示 Utils。 此 utils 适用于 Power BI 视觉对象中的工具提示自定义。

先决条件

若要使用该包，需要：

安装

要安装包，应在包含当前视觉对象的目录中运行以下命令：

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;

IVisualHost 提供 ITooltipService。

示例：

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;

Touch events

目前，工具提示 utils 可以处理多个触摸事件，非常适用于移动开发。

touchStartEventName

function touchStartEventName(): string

此方法返回触摸开始事件名称。

touchEndEventName

function touchEndEventName(): string

此方法返回触摸结束事件名称。

usePointerEvents

function usePointerEvents(): boolean

此方法返回当前 touchStart 事件是否与指针关联。