Adicionar dicas de ferramenta aos visuais do Power BI
Dicas de ferramenta são uma forma elegante de fornecer mais informações contextuais e detalhes sobre pontos de dados em um visual. A API de dicas de ferramenta do Power BI pode lidar com as seguintes interações:
- mostrar uma dica de ferramenta;
- ocultar uma dica de ferramenta;
- mover uma dica de ferramenta.
Dicas de ferramenta podem exibir um elemento textual com um título, um valor em uma determinada cor e opacidade em um conjunto especificado de coordenadas. Esses dados são fornecidos à API e o host do Power BI renderiza-os do mesmo modo que renderiza dicas de ferramenta para visuais nativos.
Você pode atualizar o estilo das dicas de ferramenta ou habilitar o recurso de dicas de ferramenta modernas para adicionar ações de drilling.
Uma dica de ferramenta em um gráfico de barras de exemplo é mostrada na imagem a seguir:
A imagem de dica de ferramenta anterior ilustra apenas uma categoria de barra e valor. Você pode estender a dica de ferramenta para exibir vários valores.
Gerenciar dicas de ferramenta
Você pode gerenciar as dicas de ferramenta em seu visual por meio da interface ITooltipService. 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;
}
O visual deve detectar os eventos de mouse que ocorrerem nele e chamar os delegados show(), move() e hide() conforme necessário, com o conteúdo apropriado populado nos objetos options da dica de ferramenta.
TooltipShowOptions e TooltipHideOptions, por sua vez, definem o que exibir e como se comportar caso esses eventos ocorressem.
Já que a chamada desses métodos envolve eventos do usuário, como movimentos do mouse ou eventos de toque, é uma boa ideia criar ouvintes para esses eventos, que, por sua vez, invocarão os membros TooltipService.
O exemplo a seguir agrega em uma classe chamada TooltipServiceWrapper.
A classe TooltipServiceWrapper
O propósito básico dessa classe é conter a instância do TooltipService, ouvir eventos de mouse D3 em elementos relevantes e, em seguida, fazer as chamadas para os elementos hide() e show() quando necessário.
A classe mantém e gerencia qualquer estado e lógica relevantes para esses eventos, que são voltados principalmente para a interface com o código D3 subjacente. A interface e a conversão de D3 estão 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 membro TooltipServiceWrapper, que é instanciado no construtor com a instância de host tooltipService.
private tooltipServiceWrapper: ITooltipServiceWrapper;
this.tooltipServiceWrapper = createTooltipServiceWrapper(this.host.tooltipService, options.element);
A classe TooltipServiceWrapper contém a instância tooltipService, também como o elemento raiz D3 dos parâmetros visuais 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 ponto de entrada único para essa classe registrar ouvintes de evento é o método addTooltip.
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;
}
...
...
}
- selection: d3.Selection<Element>: os elementos d3 sobre quais dicas de ferramenta são manipuladas.
- getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: o delegado para popular o conteúdo da dica de ferramenta (o que exibir) segundo o contexto.
- getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: o delegado para recuperar a ID do ponto de dados (não usado neste exemplo).
- Booliano reloadTooltipDataOnMouseMove? : Um booliano indicando se os dados da dica de ferramenta devem ser atualizados durante um evento MouseMove (não usado neste exemplo).
Como você pode ver, addTooltip sairá sem realizar nenhuma ação se o tooltipService estiver desabilitado ou se não houver nenhuma seleção real.
Chame o método show para exibir uma dica de ferramenta
O método addTooltip em seguida ouve 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 elementos D3 selecionados em um ToolTipEventArgs. Também calcula as coordenadas.
- getTooltipInfoDelegate: em seguida, ele cria o conteúdo da dica de ferramenta com base em tooltipEventArgs. É um retorno de chamada para a classe BarChart, pois representa a lógica do visual. É o conteúdo de texto real a ser exibido na dica de ferramenta.
- getDataPointIdentity: não usado neste exemplo.
- this.visualHostTooltipService.show: a chamada para exibir a dica de ferramenta.
Tratamento adicional pode ser encontrado no exemplo para os eventos mouseout e mousemove.
Para obter mais informações, confira o repositório visual SampleBarChart.
Preencher o conteúdo da dica de ferramenta pelo método getTooltipData
A classe BarChart foi adicionada com um membro getTooltipData que simplesmente extrai category, value e color do ponto de dados para 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 membro header é 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, o que adiciona várias linhas à dica de ferramenta. Isso pode ser útil em visuais como gráficos de barras empilhadas, em que a dica de ferramenta pode exibir dados de mais do que um único ponto de dados.
Chamar o método addTooltip
A etapa final é chamar o método addTooltip quando os dados reais podem mudar. Essa chamada ocorre no método BarChart.update(). É feita uma chamada para monitorar a seleção de todos os elementos bar, passando apenas o BarChart.getTooltipData(), conforme já mencionado.
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 do relatório
Para adicionar suporte a dicas de ferramentas de página de relatório (a capacidade de modificar dicas de ferramentas no painel de formato da página de relatório), adicione um tooltips objeto no arquivo capabilities.json .
Por exemplo:
{
"tooltips": {
"supportedTypes": {
"default": true,
"canvas": true
},
"roles": [
"tooltips"
]
}
}
Em seguida, você pode definir as dicas de ferramenta no Painel formatação da página do relatório.
supportedTypes: a configuração da dica de ferramenta compatível com o visual e refletida no contêiner de campos.default: Especifica se a associação de dicas de ferramenta "automática" por meio do campo de dados é compatível.canvas: Especifica se as dicas de ferramenta de página de relatório são compatíveis.
roles: (Opcional) Depois de definido, ele instrui quais funções de dados estão associadas à opção de dica de ferramenta selecionada no contêiner de campos.
Para obter mais informações, confira Diretrizes de uso de dicas de ferramenta deda página de relatório.
Para exibir a dica de ferramenta da página de relatório, depois que o host do Power BI chama ITooltipService.Show(options: TooltipShowOptions) ou ITooltipService.Move(options: TooltipMoveOptions), ele consome selectionId (propriedade identities do argumento options anterior). A ser recuperada pela dica de ferramenta, SelectionId deve representar os dados selecionados (categoria, série e assim por diante) do item que você focalizou.
Um exemplo de envio de selectionId para chamadas de exibição de dica de ferramenta é 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 a dicas de ferramentas modernas na página do relatório
Na versão de API 3.8.3, você também pode criar dicas de ferramenta visuais modernas. As dicas de ferramenta visuais modernas adicionam ações de drill de ponto de dados às suas dicas de ferramenta e atualizam o estilo para corresponder ao seu tema de relatório. Para descobrir qual versão você está usando, verifique apiVersion no arquivo pbiviz.json.
Para gerenciar o suporte a dicas de ferramentas modernas da página de relatório, adicione a supportEnhancedTooltips propriedade ao tooltips objeto no arquivo capabilities.json .
Por exemplo:
{
"tooltips": {
... ,
"supportEnhancedTooltips": true
}
}
Veja um exemplo do recurso de dicas de ferramentas modernas que está sendo usado no código SampleBarChart.
Observação
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 usuário ainda precisará habilitar o recurso de dicas de ferramentas modernas nas configurações do relatório.