Aggiungere descrizioni comando agli oggetti visivi di Power BI

  • Articolo

Le descrizioni comando sono un modo elegante di offrire altre informazioni contestuali e dettagli ai punti dati su un oggetto visivo. L'API delle descrizioni comando di Power BI può gestire le interazioni seguenti:

  • Visualizzazione di una descrizione comando.
  • Rimozione di una descrizione comando.
  • Spostamento di una descrizione comando.

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

È possibile modificare lo stile delle descrizioni comando o aggiungere azioni di drill-drill abilitando la funzionalità delle descrizioni comando moderne.

L'immagine seguente mostra una descrizione comando in un grafico a barre di esempio:

Screenshot che mostra le descrizioni comando del grafico a barre di esempio.

L'immagine della descrizione comando precedente presenta una singola categoria e un valore per la barra. È possibile estendere la descrizione comando per visualizzare più valori.

Gestire le descrizioni comando

È possibile gestire le descrizioni comando nell'oggetto visivo tramite l'interfaccia ITooltipService. ITooltipService notifica all'host che è necessario visualizzare, rimuovere o spostare una descrizione comando.

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

L'oggetto visivo deve rilevare gli eventi del mouse all'interno dell'oggetto visivo e chiamare i delegati show(), move() e hide(), in base alle esigenze, con il contenuto appropriato popolato negli oggetti options descrizione comando. TooltipShowOptions e TooltipHideOptions a loro volta definiscono cosa visualizzare e come comportarsi in presenza di questi eventi.

La chiamata di questi metodi comporta eventi utente come gli spostamenti del mouse ed eventi di tocco, quindi è consigliabile creare listener per questi eventi, che a loro volta richiameranno i membri TooltipService. Nell'esempio seguente viene eseguita l'aggregazione in una classe denominata TooltipServiceWrapper.

Classe TooltipServiceWrapper

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.

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. L'interazione e la conversione del codice D3 non rientrano nell'ambito di questo articolo.

Il codice di esempio in questo articolo è basato sull'oggetto visivo SampleBarChart. È possibile esaminare il codice sorgente in barChart.ts.

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

        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.

    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.

Metodo 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;
            }
        ...
        ...
        }
  • selezione: d3. Selezione<Elemento>: gli elementi d3 su cui vengono gestite le descrizioni comando.
  • getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: delegato per popolare il contenuto della descrizione comando (cosa visualizzare) per contesto.
  • getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: delegato per il recupero dell'ID punto dati (inutilizzato in questo esempio).
  • reloadTooltipDataOnMouseMove? booleano: valore booleano che indica se aggiornare i dati della descrizione comando durante un evento MouseMove (non usato in questo esempio).

Come si può notare, il metodo addTooltip termina senza alcuna azione se tooltipService è disabilitato o se non esiste una selezione reale.

Chiamare il metodo Show per visualizzare una descrizione comando

Il metodo addTooltip è successivamente in ascolto dell'evento mouseover D3, come illustrato nel codice seguente:

        ...
        ...
        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. Calcola anche le coordinate.
  • getTooltipInfoDelegate: compila quindi il contenuto della descrizione comando dalla descrizione comandoEventArgs. Questo è un callback alla classe BarChart, perché si tratta della logica dell'oggetto visivo. È l'effettivo contenuto di testo da visualizzare nella descrizione comando.
  • getDataPointIdentity: non usato in questo esempio.
  • this.visualHostTooltipService.show: chiamata per visualizzare la descrizione comando.

Altre informazioni sulla gestione sono disponibili nell'esempio per gli eventi mouseout e mousemove.

Per altre informazioni, vedere il repository dell'oggetto visivo SampleBarChart.

Popolare il contenuto della descrizione comando tramite il metodo getTooltipData

La classe BarChart è stata aggiunta con un membro getTooltipData, che estrae semplicemente category, value e color del punto dati in un elemento VisualTooltipDataItem[].

        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. È possibile immettere più di un elemento in VisualTooltipDataItem[] per aggiungere più righe alla descrizione comando. Questo può essere utile negli oggetti visivi, ad esempio i grafici a barre in pila, in cui la descrizione comando potrebbe visualizzare dati da più di un punto dati.

Chiamare il metodo addTooltip

Il passaggio finale consiste nel chiamare il metodo addTooltip quando i dati effettivi possono cambiare. Questa chiamata viene eseguita nel metodo BarChart.update(). Viene effettuata una chiamata per monitorare la selezione di tutti gli elementi "bar", passando solo BarChart.getTooltipData(), come indicato in precedenza.

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

Aggiungere il supporto delle descrizioni comando alla pagina del report

Per aggiungere il supporto delle descrizioni comando della pagina del report (possibilità di modificare le descrizioni comando nel riquadro formato della pagina del report), aggiungere un tooltips oggetto nel file capabilities.json.

Ad esempio:

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

È quindi possibile definire le descrizioni comando dal riquadro Formattazione della pagina del report.

  • supportedTypes: è la configurazione delle descrizioni comando supportata dall'oggetto visivo e riflessa nell'area campi.
    • default: specifica se è supportata l'associazione di descrizioni comando "automatiche" tramite il campo dati.
    • canvas: specifica se sono supportate le descrizioni comando della pagina del report.
  • roles: (facoltativo) dopo essere stato definito, indica quali ruoli dati vengono associati all'opzione selezionata per le descrizioni comando nell'area campi.

Screenshot che mostra la finestra di dialogo Descrizione comando pagina report.

Per altre informazioni, vedere Linee guida sull'utilizzo delle descrizioni comando della pagina del report.

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

Un esempio di invio di selectionId alle chiamate di visualizzazione delle descrizioni comando è illustrato nel codice seguente:

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

Aggiungere il supporto delle descrizioni comando moderne alla pagina del report

Dall'API versione 3.8.3 è anche possibile creare descrizioni comando visive moderne. Le descrizioni comando visive moderne aggiungono azioni di drill del punto dati alle descrizioni comando e aggiornano lo stile in modo che corrisponda al tema del report. Per scoprire quale versione si sta usando, archiviare apiVersion nel file pbiviz.json.

Screenshot che mostra una descrizione comando moderna.

Per gestire il supporto delle descrizioni comando moderne della pagina del report, aggiungere la proprietà supportEnhancedTooltips all'tooltipsoggetto nel file capabilities.json.

Ad esempio:

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

Vedere un esempio della funzionalità moderna delle descrizioni comando in uso nel codice SampleBarChart.

Nota

L'aggiunta di questa funzionalità al file capabilities.json consente all'utente di abilitare questa funzionalità per il report. Tenere presente che l'utente dovrà comunque abilitare la funzionalità di descrizione comando moderna nelle impostazioni del report.

Contenuto correlato