Utilitários de dicas de ferramentas

  • Artigo

Este artigo ajuda a instalar, importar e usar utilitários de dicas de ferramentas. Tratam-se de utilitários convenientes para a personalização de dicas de ferramentas em visuais do Power BI.

Requisitos

Para usar o pacote, você precisa:

Instalação

Para instalar o pacote, você deve executar o seguinte comando no diretório com seu visual atual:

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

Esse comando instala e adiciona um pacote como uma dependência no arquivo package.json.

Uso

O Guia de Uso descreve uma API pública do pacote. Você encontrará uma descrição e alguns exemplos de cada interface pública do pacote.

Esse pacote fornece uma maneira de criar TooltipServiceWrapper e métodos para ajudar a manipular ações de dicas de ferramentas. Ele utiliza as interfaces de dicas de ferramentas – ITooltipServiceWrapper, TooltipEventArgs, TooltipEnabledDataPoint.

Tem métodos específicos (manipuladores de eventos de toque) relacionados ao desenvolvimento para dispositivos móveis: touchEndEventName, touchStartEventName, usePointerEvents.

TooltipServiceWrapper fornece a maneira mais simples de manipular as dicas de ferramentas.

Esse módulo fornece a seguinte função e interface:

createTooltipServiceWrapper

Essa função cria uma instância de ITooltipServiceWrapper.

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

O ITooltipService está disponível em IVisualHost.

Exemplo:

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.
    }
}

Veja um exemplo do visual personalizado aqui.

ITooltipServiceWrapper

Essa interface descreve métodos públicos e propriedades do 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

Esse método adiciona dicas de ferramentas à seleção atual.

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

Exemplo:

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.

Veja um exemplo do visual personalizado aqui.

Veja um exemplo de personalização de dica de ferramenta em um visual personalizado de Gantt aqui.

ITooltipServiceWrapper.hide

Esse método oculta a dica de ferramenta.

hide(): void;

Exemplo:

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

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

tooltipServiceWrapper.hide();

Interfaces

As interfaces são usadas durante a criação e o uso do TooltipServiceWrapper. Elas são mencionadas nos exemplos dos artigos anteriores aqui.

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

Agora os utilitários de dicas de ferramentas podem manipular vários eventos de toque que são úteis no desenvolvimento para dispositivos móveis.

touchStartEventName

function touchStartEventName(): string

Esse método retorna o nome do evento de início de toque.

touchEndEventName

function touchEndEventName(): string

Esse método retorna o nome do evento de fim de toque.

usePointerEvents

function usePointerEvents(): boolean

Esse método retorna o evento touchStart atual relacionado ou não ao ponteiro.