Descrizioni comando negli oggetti visivi di Power BITooltips in Power BI visuals

Gli oggetti visivi possono ora usare il supporto per le descrizioni comando di Power BI.Visuals can now make use of Power BI tooltip support. Le descrizioni comando di Power BI gestiscono le interazioni seguenti:Power BI tooltips handle the following interactions:

  • Visualizzazione di una descrizione comando.Show a tooltip.
  • Rimozione di una descrizione comando.Hide a tooltip.
  • Spostamento di una descrizione comando.Move a tooltip.

Le descrizioni comando possono visualizzare un elemento di testo con un titolo in un colore e con un'opacità specificati in corrispondenza di un set di coordinate indicato.Tooltips can display a textual element with a title, a value in a given color, and opacity at a specified set of coordinates. Questi dati vengono forniti all'API e l'host Power BI ne esegue il rendering nello stesso modo in cui esegue il rendering delle descrizioni comando per gli oggetti visivi nativi.This data is provided to the API, and the Power BI host renders it the same way it renders tooltips for native visuals.

Nell'immagine seguente è illustrata una descrizione comando in un grafico a barre di esempio:A tooltip in a sample bar chart is shown in the following image:

Descrizioni comando del grafico a barre di esempio

L'immagine della descrizione comando precedente presenta una singola categoria e un valore per la barra.The preceding tooltip image illustrates a single bar category and value. È possibile estendere una singola descrizione comando per visualizzare più valori.You can extend a single tooltip to display multiple values.

Gestire le descrizioni comandoManage tooltips

L'interfaccia tramite cui vengono gestite le descrizioni comando è "ITooltipService".The interface through which you manage tooltips is the "ITooltipService." Viene usata per indicare all'host che è necessario visualizzare, rimuovere o spostare una descrizione comando.It's used to notify the host that a tooltip needs to be displayed, removed, or moved.

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

L'oggetto visivo deve essere in ascolto degli eventi del mouse al suo interno e chiamare i delegati show(), move() e hide(), in base alle esigenze, con il contenuto appropriato immesso negli oggetti Tooltip****Options.Your visual needs to listen to the mouse events within your visual and call the show(), move(), and hide() delegates, as needed, with the appropriate content populated in the Tooltip****Options objects. TooltipShowOptions e TooltipHideOptions a loro volta definiscono cosa visualizzare e come comportarsi in presenza di questi eventi.TooltipShowOptions and TooltipHideOptions would in turn define what to display and how to behave in these events.

Poiché la chiamata di questi metodi comporta eventi utente come gli spostamenti del mouse ed eventi di tocco, è consigliabile creare listener per questi eventi, che a loro volta richiameranno i membri TooltipService.Because calling these methods involves user events such as mouse moves and touch events, it's a good idea to create listeners for these events, which would in turn invoke the TooltipService members. Aggregati di esempio in una classe denominata TooltipServiceWrapper.Our sample aggregates in a class called TooltipServiceWrapper.

Classe TooltipServiceWrapperThe TooltipServiceWrapper class

L'idea di base riguardo a questa classe consiste nel mantenere l'istanza di TooltipService, ascoltare gli eventi del mouse D3 sugli elementi pertinenti e quindi effettuare le chiamate a show() e hide() per gli elementi, come necessario.The basic idea behind this class is to hold the instance of the TooltipService, listen to D3 mouse events over relevant elements, and then make the calls to show() and hide() the elements when needed.

La classe include e gestisce tutti gli stati pertinenti e la logica per questi eventi, che per lo più sono finalizzati all'interazione con il codice D3 sottostante.The class holds and manages any relevant state and logic for these events, which are mostly geared at interfacing with the underlying D3 code. L'interazione e la conversione del codice D3 non rientrano nell'ambito di questo articolo.The D3 interfacing and conversion is out of scope for this article.

Il codice di esempio completo è disponibile nel repository dell'oggetto visivo SampleBarChart.You can find the full sample code in SampleBarChart visual repository.

Creare TooltipServiceWrapperCreate TooltipServiceWrapper

Il costruttore del grafico a barre include ora un membro TooltipServiceWrapper, di cui viene creata un'istanza nel costruttore con l'istanza tooltipService host.The bar chart constructor now has a TooltipServiceWrapper member, which is instantiated in the constructor with the host tooltipService instance.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

La classe TooltipServiceWrapper contiene l'istanza tooltipService, anche come elemento D3 radice dei parametri visual e touch.The TooltipServiceWrapper class holds the tooltipService instance, also as the root D3 element of the visual and touch parameters.

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

Il singolo punto di ingresso per questa classe per la registrazione dei listener di eventi è il metodo addTooltip.The single entry point for this class to register event listeners is the addTooltip method.

Metodo addTooltipThe addTooltip method

        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 : elementi D3 su cui vengono gestite le descrizioni comando.selection: d3.Selection: The d3 elements over which tooltips are handled.

  • getTooltipInfoDelegate: (args: TooltipEventArgs) => VisualTooltipDataItem[] : delegato per l'immissione del contenuto della descrizione comando (che cosa visualizzare) per ogni contesto.getTooltipInfoDelegate: (args: TooltipEventArgs) => VisualTooltipDataItem[]: The delegate for populating the tooltip content (what to display) per context.

  • getDataPointIdentity: (args: TooltipEventArgs) => ISelectionId: delegato per il recupero dell'ID punto dati (non usato in questo esempio).getDataPointIdentity: (args: TooltipEventArgs) => ISelectionId: The delegate for retrieving the data point ID (unused in this sample).

  • reloadTooltipDataOnMouseMove? boolean: valore booleano che indica se aggiornare i dati della descrizione comando durante un evento MouseMove (non usato in questo esempio).reloadTooltipDataOnMouseMove? boolean: A Boolean that indicates whether to refresh the tooltip data during a MouseMove event (unused in this sample).

Come si può notare, il metodo addTooltip termina senza alcuna azione se tooltipService è disabilitato o se non esiste una selezione reale.As you can see, addTooltip exits with no action if the tooltipService is disabled or there's no real selection.

Chiamare il metodo Show per visualizzare una descrizione comandoCall the show method to display a tooltip

Il metodo addTooltip è successivamente in ascolto dell'evento mouseover D3, come illustrato nel codice seguente:The addTooltip method next listens to the D3 mouseover event, as shown in the following code:

        ...
        ...
        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: Estrae il contesto dagli elementi D3 selezionati in un oggetto tooltipEventArgs.makeTooltipEventArgs: Extracts the context from the D3 selected elements into a tooltipEventArgs. Calcola anche le coordinate.It calculates the coordinates as well.

  • getTooltipInfoDelegate: compila quindi il contenuto della descrizione comando da tooltipEventArgs.getTooltipInfoDelegate: It then builds the tooltip content from the tooltipEventArgs. Questo è un callback alla classe BarChart, perché si tratta della logica dell'oggetto visivo.It's a callback to the BarChart class, because it is the visual's logic. È l'effettivo contenuto di testo da visualizzare nella descrizione comando.It's the actual text content to display in the tooltip.

  • getDataPointIdentity: non usato in questo esempio.getDataPointIdentity: Unused in this sample.

  • this.visualHostTooltipService.show: chiamata per visualizzare la descrizione comando.this.visualHostTooltipService.show: The call to display the tooltip.

Altre informazioni sulla gestione sono disponibili nell'esempio per gli eventi mouseout e mousemove.Additional handling can be found in the sample for mouseout and mousemove events.

Per altre informazioni, vedere il repository dell'oggetto visivo SampleBarChart.For more information, see the SampleBarChart visual repository.

Popolare il contenuto della descrizione comando tramite il metodo getTooltipDataPopulate the tooltip content by the getTooltipData method

La classe BarChart è stata aggiunta con un membro getTooltipData, che estrae semplicemente category, value e color del punto dati in un elemento VisualTooltipDataItem[].The BarChart class was added with a getTooltipData member, which simply extracts the category, value, and color of the data point into a VisualTooltipDataItem[] element.

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

Nell'implementazione precedente il membro header è costante, ma è possibile usarlo per implementazioni più complesse, che richiedono valori dinamici.In the preceding implementation, the header member is constant, but you can use it for more complex implementations, which require dynamic values. È possibile immettere più di un elemento in VisualTooltipDataItem[] per aggiungere più righe alla descrizione comando.You can populate the VisualTooltipDataItem[] with more than one element, which adds multiple lines to the tooltip. Questo può essere utile negli oggetti visivi, ad esempio i grafici a barre in pila, in cui la descrizione comando può visualizzare dati da più di un punto dati.It can be useful in visuals such as stacked bar charts where the tooltip may display data from more than a single data point.

Chiamare il metodo addTooltipCall the addTooltip method

Il passaggio finale consiste nel chiamare il metodo addTooltip quando i dati effettivi possono cambiare.The final step is to call the addTooltip method when the actual data might change. Questa chiamata viene eseguita nel metodo BarChart.update().This call takes place in the BarChart.update() method. Viene effettuata una chiamata per monitorare la selezione di tutti gli elementi "bar", passando solo BarChart.getTooltipData(), come indicato in precedenza.A call is made to monitor the selection of all the 'bar' elements, passing only the BarChart.getTooltipData(), as mentioned previously.

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

Aggiungere le descrizioni comando per le pagine del reportAdd report page tooltips

Per aggiungere il supporto per le descrizioni comando della pagina del report, la maggior parte delle modifiche si troverà nel file capabilities.json.To add report page tooltips support, you'll find most changes in the capabilities.json file.

Uno schema di esempio èA sample schema is

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

È possibile definire le descrizioni comando della pagina del report nel riquadro Formato.You can define report page tooltips in the Format pane.

Descrizione comando della pagina del report

  • supportedTypes: è la configurazione delle descrizioni comando supportata dall'oggetto visivo e riflessa nell'area campi.supportedTypes: The tooltip configuration that's supported by the visual and reflected in the fields well.

    • default: specifica se è supportata l'associazione di descrizioni comando "automatiche" tramite il campo dati.default: Specifies whether the "automatic" tooltips binding via the data field is supported.
    • canvas: specifica se sono supportate le descrizioni comando della pagina del report.canvas: Specifies whether the report page tooltips are supported.
  • roles: (facoltativo) dopo essere stato definito, indica quali ruoli dati vengono associati all'opzione selezionata per le descrizioni comando nell'area campi.roles: (Optional) After it's defined, it instructs what data roles are bound to the selected tooltip option in the fields well.

Per altre informazioni, vedere Linee guida sull'utilizzo delle descrizioni comando della pagina del report.For more information, see Report page tooltips usage guidelines.

Per visualizzare la descrizione comando della pagina del report, dopo che l'host Power BI chiama ITooltipService.Show(options: TooltipShowOptions) o ITooltipService.Move(options: TooltipMoveOptions), utilizza selectionId (proprietà identities dell'argomento options precedente).To display the report page tooltip, after the Power BI host calls ITooltipService.Show(options: TooltipShowOptions) or ITooltipService.Move(options: TooltipMoveOptions), it consumes the selectionId (identities property of the preceding options argument). SelectionId, per essere recuperato dalla descrizione comando, deve rappresentare i dati selezionati (categoria, serie e così via) dell'elemento su cui è stato posizionato il puntatore del mouse.To be retrieved by the tooltip, SelectionId should represent the selected data (category, series, and so on) of the item you hovered over.

Un esempio di invio di selectionId alle chiamate di visualizzazione delle descrizioni comando è illustrato nel codice seguente:An example of sending the selectionId to tooltip display calls is shown in the following code:

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