Partilhar via

Adicionar dicas de ferramentas aos visuais do Power BI

As dicas de ferramentas são uma maneira elegante de fornecer mais informações contextuais e detalhes para pontos de dados em um visual. A API de dicas de ferramentas do Power BI pode lidar com as seguintes interações:

  • Mostrar uma dica de ferramenta.
  • Oculte uma dica de ferramenta.
  • Mova uma dica de ferramenta.

As tooltips podem exibir um elemento textual com um título, um valor em uma determinada cor e opacidade numa posição especificada de coordenadas. Esses dados são fornecidos à API e o host do Power BI os renderiza da mesma forma que renderiza dicas de ferramentas para visuais nativos.

Você pode alterar o estilo das suas dicas de ferramentas ou adicionar ações de exploração detalhada ativando a funcionalidade de dicas de ferramentas modernas.

A imagem a seguir mostra uma dica de ferramenta em um gráfico de barras de exemplo:

Captura de tela que mostra exemplos de dicas de ferramentas de gráfico de barras.

A imagem da dica de ferramenta acima representa uma única categoria de barra e o seu valor. Pode expandir o tooltip para exibir vários valores.

Gerenciar dicas de ferramentas

Você pode gerenciar as dicas de ferramentas em seu visual através da ITooltipService interface. ITooltipService Notifica o host de que uma dica de ferramenta precisa ser exibida, removida ou movida.

    interface ITooltipService {
        enabled(): boolean;
        show(options: TooltipShowOptions): void;
        move(options: TooltipMoveOptions): void;
        hide(options: TooltipHideOptions): void;
    }

Seu visual deve detetar eventos do mouse dentro do visual e chamar os delegados show(), move() e hide(), conforme necessário, com o conteúdo apropriado preenchido nos objetos Tooltip options. TooltipShowOptions e TooltipHideOptions, por sua vez, definem o que exibir e como se comportar em eventos.

Chamar esses métodos envolve eventos do usuário, como movimentos do mouse e eventos de toque, por isso é uma boa ideia criar ouvintes para esses eventos, que, por sua vez, invocariam os TooltipService membros. O exemplo a seguir agrega-se numa classe denominada TooltipServiceWrapper.

A classe TooltipServiceWrapper

A ideia básica por trás dessa classe é manter a instância do , ouvir eventos do TooltipServicemouse D3 sobre elementos relevantes e, em seguida, fazer as chamadas para show() e hide() os elementos quando necessário.

A classe mantém e gerencia qualquer estado e lógica relevantes para esses eventos, que são principalmente voltados para interface com o código D3 subjacente. A interface e conversão D3 está fora do escopo deste artigo.

O código de exemplo neste artigo é baseado no visual SampleBarChart. Você pode examinar o código-fonte em barChart.ts.

Criar TooltipServiceWrapper

O construtor de gráfico de barras agora tem um TooltipServiceWrapper membro, que é instanciado no construtor com a instância do host tooltipService .

        private tooltipServiceWrapper: ITooltipServiceWrapper;

        this.tooltipServiceWrapper = createTooltipServiceWrapper(this.host.tooltipService, options.element);

A TooltipServiceWrapper classe mantém a tooltipService instância, também como o elemento D3 raiz dos parâmetros visual e de toque.

    class TooltipServiceWrapper implements ITooltipServiceWrapper {
        private handleTouchTimeoutId: number;
        private visualHostTooltipService: ITooltipService;
        private rootElement: Element;
        private handleTouchDelay: number;

        constructor(tooltipService: ITooltipService, rootElement: Element, handleTouchDelay: number) {
            this.visualHostTooltipService = tooltipService;
            this.handleTouchDelay = handleTouchDelay;
            this.rootElement = rootElement;
        }
        .
        .
        .
    }

O único ponto de entrada para essa classe registrar ouvintes de eventos é o addTooltip método.

O método addTooltip

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

            if (!selection || !this.visualHostTooltipService.enabled()) {
                return;
            }
        ...
        ...
        }
  • seleção: d3.Selection Element<>: os Elementos d3 nos quais os tooltips são manipulados.
  • getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: O delegado para preencher o conteúdo da dica de ferramenta (o que exibir) por contexto.
  • getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: O delegado para recuperar o ID do ponto de dados (não usado neste exemplo).
  • reloadTooltipDataOnMouseMove? booleano: um booleano que indica se os dados da dica de ferramenta devem ser atualizados durante um evento MouseMove (não usado neste exemplo).

Como você pode ver, addTooltip sai sem ação se o tooltipService estiver desativado ou não houver seleção real.

Chamar o método show para exibir uma dica de ferramenta

O próximo método escuta o evento D3 mouseover, conforme mostrado no código a seguir:

        ...
        ...
        selection.on("mouseover.tooltip", () => {
            // Ignore mouseover while handling touch events
            if (!this.canDisplayTooltip(d3.event))
                return;

            let tooltipEventArgs = this.makeTooltipEventArgs<T>(rootNode, true, false);
            if (!tooltipEventArgs)
                return;

            let tooltipInfo = getTooltipInfoDelegate(tooltipEventArgs);
            if (tooltipInfo == null)
                return;

            let selectionId = getDataPointIdentity(tooltipEventArgs);

            this.visualHostTooltipService.show({
                coordinates: tooltipEventArgs.coordinates,
                isTouchEvent: false,
                dataItems: tooltipInfo,
                identities: selectionId ? [selectionId] : [],
            });
        });
  • makeTooltipEventArgs: extrai o contexto dos "D3 elementos selecionados" para um tooltipEventArgs. Ele também calcula as coordenadas.
  • getTooltipInfoDelegate: Em seguida, ele cria o conteúdo da dica de ferramenta a partir do tooltipEventArgs. É uma chamada de retorno para a classe BarChart, porque é a lógica do gráfico. É o conteúdo de texto real a ser exibido na dica de ferramenta.
  • getDataPointIdentity: Não utilizado neste exemplo.
  • this.visualHostTooltipService.show: A chamada para exibir a dica de ferramenta.

Manipulação adicional pode ser encontrada no exemplo de eventos mouseout e mousemove.

Para obter mais informações, consulte o repositório visual SampleBarChart.

Preencher o conteúdo da dica de ferramenta através do método getTooltipData

A classe BarChart foi adicionada com um getTooltipData membro, que simplesmente extrai o category, valuee color do ponto de dados em um elemento VisualTooltipDataItem[].

        private static getTooltipData(value: any): VisualTooltipDataItem[] {
            return [{
                displayName: value.category,
                value: value.value.toString(),
                color: value.color,
                header: 'ToolTip Title'
            }];
        }

Na implementação anterior, o header membro é constante, mas você pode usá-lo para implementações mais complexas, que exigem valores dinâmicos. Você pode preencher o VisualTooltipDataItem[] com mais de um elemento, adicionando várias linhas à dica de ferramenta. Isto pode ser útil em elementos visuais, como gráficos de barras empilhadas, onde o tooltip pode exibir dados de mais de um único ponto de dados.

Chamar o método addTooltip

A etapa final é chamar o addTooltip método quando os dados reais podem mudar. Esta chamada ocorre no BarChart.update() método. Uma chamada é feita para supervisionar a seleção de todos os elementos da "barra", passando apenas o BarChart.getTooltipData(), conforme mencionado anteriormente.

        this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
            (tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
            (tooltipEvent: TooltipEventArgs<number>) => null);

Adicionar suporte a dicas de ferramentas à página de relatório

Para adicionar suporte a dicas de ferramentas da página de relatório (a capacidade de modificar dicas de ferramentas no painel de formatação da página de relatório), adicione um tooltipsobjeto no arquivo capabilities.json.

Por exemplo:

{
    "tooltips": {
        "supportedTypes": {
            "default": true,
            "canvas": true
        },
        "roles": [
            "tooltips"
        ]
    }
}

Em seguida, pode definir as dicas de ferramentas a partir do Painel de Formatação da página do relatório.

  • supportedTypes: A configuração da dica de ferramenta suportada pelo elemento visual e refletida adequadamente nos campos.
    • default: Especifica se a vinculação de dicas de ferramentas "automática" por meio do campo de dados é suportada.
    • canvas: Especifica se as dicas de ferramentas da página de relatório são suportadas.
  • roles: (Opcional) Depois de definido, ele instrui quais funções de dados estão vinculadas à opção de dica de ferramenta selecionada nos campos.

Captura de ecrã que mostra a caixa de diálogo da dica de ferramenta da página do Relatório.

Para obter mais informações, consulte Diretrizes de uso de dicas de ferramentas da página de relatório.

Para apresentar a dica de ferramenta da página de relatório, após o host do Power BI chamar ITooltipService.Show(options: TooltipShowOptions) ou ITooltipService.Move(options: TooltipMoveOptions), ele utiliza o selectionId (propriedade identities do argumento precedente options). Para ser recuperado pelo tooltip, SelectionId deve representar o dado selecionado (categoria, série e assim por diante) do item sobre o qual você passou o cursor.

Um exemplo de envio do selectionId para chamadas de exibição de tooltip é mostrado no código a seguir:

    this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
        (tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
        (tooltipEvent: TooltipEventArgs<number>) => tooltipEvent.data.selectionID);

Adicionar suporte para dicas de ferramentas modernas à página de relatório

A partir da versão 3.8.3 da API, pode-se também criar modernas dicas de ferramentas visuais. As dicas de ferramentas visuais modernas adicionam ações de detalhamento de ponto de dados às suas dicas de ferramentas e atualizam o estilo para corresponder ao tema do relatório. Para saber qual versão você está usando, verifique a apiVersionno arquivo pbiviz.json .

Captura de ecrã que mostra um tooltip moderno.

Para gerir o suporte para as tooltips modernas na página de relatório, adicione a propriedade ao objeto no arquivo capabilities.json.

Por exemplo:

{
    "tooltips": {
        ... ,
        "supportEnhancedTooltips": true
    }
}

Veja um exemplo do recurso moderno de dicas de ferramentas que está sendo usado no código SampleBarChart .

Nota

Adicionar esse recurso ao arquivo capabilities.json dá ao usuário a possibilidade de habilitar esse recurso para o relatório. Lembre-se de que o utilizador ainda terá de ativar a funcionalidade moderna de dica de ferramenta nas configurações do relatório.

Conteúdos relacionados

  • Last updated on