Utilitários de dicas de ferramentasTooltip utils

Este artigo ajuda a instalar, importar e usar utilitários de dicas de ferramentas.This article will help you to install, import, and use tooltip utils. Tratam-se de utilitários convenientes para a personalização de qualquer dica de ferramenta em visuais do Power BI.This util useful for any tooltip customization in Power BI visuals.

RequisitosRequirements

Para usar o pacote, é necessário ter o seguinte:To use the package, you should have the following things:

InstalaçãoInstallation

Para instalar o pacote, você deve executar o seguinte comando no diretório com seu visual atual:To install the package, you should run the following command in the directory with your current visual:

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

Esse comando instala e adiciona um pacote como uma dependência no package.jsonThis command installs the package and adds a package as a dependency to your package.json

UsoUsage

O Guia de Uso descreve uma API pública do pacote.The Usage Guide describes a public API of the package. Você encontrará uma descrição e alguns exemplos de cada interface pública do pacote.You will find a description and a few examples for each public interface of the package.

O conteúdo desse pacote fornece uma maneira de criar TooltipServiceWrapper e métodos para ajudar a manipular ações de dicas de ferramentas.This package contains provide you the way to create TooltipServiceWrapper and methods to help handle tooltip actions. Ele utiliza as interfaces de dicas de ferramentas – ITooltipServiceWrapper, TooltipEventArgs, TooltipEnabledDataPoint.It uses tooltip interfaces - ITooltipServiceWrapper, TooltipEventArgs, TooltipEnabledDataPoint.

Também tem métodos específicos (manipuladores de eventos de toque) relacionados ao desenvolvimento para dispositivos móveis: touchEndEventName, touchStartEventName, usePointerEvents.Also it has specific methods (touch events handlers) related to mobile development: touchEndEventName, touchStartEventName, usePointerEvents.

TooltipServiceWrapper fornece a maneira mais simples de manipular dicas de ferramentas.TooltipServiceWrapper provides the simplest way in order to manipulate tooltips.

Esse módulo fornece a seguinte função e interface:This module provides the following interface and function:

createTooltipServiceWrapper

Essa função cria uma instância do ITooltipServiceWrapper.This function creates an instance of ITooltipServiceWrapper.

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

O ITooltipService está disponível em IVisualHost.The ITooltipService is available in IVisualHost.

ExemploExample

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

Você pode dar uma olhada no código de exemplo do visual personalizado aqui.You can take a look at the example code of the custom visual here.

ITooltipServiceWrapper

Essa interface descreve métodos públicos e propriedades do TooltipService.This interface describes public methods of the 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.This method adds tooltips to the current selection.

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

ExemploExample

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.

Você pode dar uma olhada no código de exemplo do visual personalizado aqui.You can take a look at the example code of the custom visual here.

Além disso, preste atenção no seguinte exemplo de personalização de dica de ferramenta no visual personalizado de Gantt aquiAlso pay attention at following example of tooltip customization in Gantt custom visual here

ITooltipServiceWrapper.hide

Esse método oculta a dica de ferramenta.This method hides the tooltip.

hide(): void;

ExemploExample

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

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

tooltipServiceWrapper.hide();

Interfaces

Essas interfaces são usadas durante a criação e o uso do TooltipServiceWrapper.This interfaces are used during TooltipServiceWrapper creation and it's usage. Também são mencionadas nos exemplos do tópico anterior aqui.Also they were mentioned in examples from previous topic here.

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

Agora os utilitários de dicas de ferramentas têm a capacidade de manipular vários eventos de toque convenientes ao desenvolvimento para dispositivos móveis.Now tooltip utils has ability to handle several touch events useful for mobile development.

touchStartEventName

function touchStartEventName(): string

Esse método retorna o nome do evento de início de toque.This method returns touch start event name.

touchEndEventName

function touchEndEventName(): string

Esse método retorna o nome do evento de início de toque.This method returns touch start event name.

usePointerEvents

function usePointerEvents(): boolean

Esse método retorna se o evento touchStart atual está relacionado ou não ao ponteiro.This method returns is current touchStart event related to pointer or not.