Aggiungere descrizioni comando agli oggetti visivi di Power BI

Le descrizioni comando sono un modo elegante per fornire informazioni più contestuali e dettagli ai punti dati in un oggetto visivo. L'API delle descrizioni comando di Power BI può gestire le interazioni seguenti:

• Visualizzare una descrizione comando.
• Nascondere una descrizione comando.
• Spostare una descrizione comando.

Le descrizioni comando possono visualizzare un elemento testuale con un titolo, un valore in un determinato colore e opacità in corrispondenza di un set specificato di coordinate. Questi dati vengono forniti all'API e l'host di 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à moderna delle descrizioni comando .

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

L'immagine della descrizione comando precedente illustra una singola categoria e un valore della 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 una descrizione comando deve essere visualizzata, rimossa o spostata.

    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 show()delegati , move()e hide() in base alle esigenze, con il contenuto appropriato popolato negli oggetti descrizione options comando. TooltipShowOptions e TooltipHideOptions a sua volta definire cosa visualizzare e come comportarsi in questi eventi.

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

Classe TooltipServiceWrapper

L'idea di base alla base di questa classe consiste nel contenere l'istanza di TooltipService, ascoltare gli eventi del mouse D3 sugli elementi pertinenti e quindi effettuare le chiamate a show() e hide() gli elementi quando necessario.

La classe contiene e gestisce qualsiasi stato e logica pertinente per questi eventi, che sono destinati principalmente all'interazione con il codice D3 sottostante. L'interfaccia e la conversione 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 dispone ora di un membro, di cui viene creata un'istanza TooltipServiceWrapper nel costruttore con l'istanza host tooltipService .

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

La TooltipServiceWrapper classe contiene l'istanza tooltipService , anche come elemento D3 radice dei parametri visivi e tocco.

    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 registrare i listener di eventi è il addTooltip metodo .

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. Elemento> Selection<: 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, addTooltip esce senza alcuna azione se è tooltipService disabilitato o non è presente alcuna selezione reale.

Chiamare il metodo show per visualizzare una descrizione comando

Il addTooltip metodo rimane quindi in ascolto dell'evento D3 mouseover , 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 selezionati D3 in una descrizione comandoEventArgs. Calcola anche le coordinate.
• getTooltipInfoDelegate: compila quindi il contenuto della descrizione comando dalla descrizione comandoEventArgs. È un callback alla classe BarChart, perché è la logica dell'oggetto visivo. Si tratta del contenuto di testo effettivo da visualizzare nella descrizione comando.
• getDataPointIdentity: non usato in questo esempio.
• this.visualHostTooltipService.show: chiamata per visualizzare la descrizione comando.

La gestione aggiuntiva è disponibile nell'esempio per mouseout gli eventi e mousemove .

Per altre informazioni, vedere il repository visivo SampleBarChart.

Popolare il contenuto della descrizione comando tramite il metodo getTooltipData

La classe BarChart è stata aggiunta con un getTooltipData membro, che estrae semplicemente , categoryvaluee 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 header membro è costante, ma è possibile usarlo per implementazioni più complesse, che richiedono valori dinamici. È possibile popolare con VisualTooltipDataItem[] più elementi, che aggiunge più righe alla descrizione comando. Può essere utile negli oggetti visivi, ad esempio grafici a barre in pila, in cui la descrizione comando potrebbe visualizzare i dati da più di un singolo punto dati.

Chiamare il metodo addTooltip

Il passaggio finale consiste nel chiamare il addTooltip metodo quando i dati effettivi potrebbero cambiare. Questa chiamata viene eseguita nel BarChart.update() metodo . 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 (la possibilità di modificare le descrizioni comando nel riquadro formato della pagina del report), aggiungere un tooltipsoggetto 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: configurazione della descrizione comando supportata dall'oggetto visivo e riflessa nell'area campi.
  • default: specifica se l'associazione delle descrizioni comando "automatica" tramite il campo dati è supportata.
  • canvas: specifica se le descrizioni comando della pagina del report sono supportate.
• roles: (Facoltativo) Dopo la definizione, indica quali ruoli dati sono associati all'opzione di descrizione comando selezionata nell'area campi.

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

Per visualizzare la descrizione comando della pagina del report, dopo che l'host di Power BI chiama ITooltipService.Show(options: TooltipShowOptions) o ITooltipService.Move(options: TooltipMoveOptions), utilizza il valore selectionId (identities proprietà dell'argomento precedente options ). Per essere recuperato dalla descrizione comando, SelectionId deve rappresentare i dati selezionati (categoria, serie e così via) dell'elemento su cui si è posizionato il puntatore del mouse.

Un esempio di invio del valore selectionId alle chiamate di visualizzazione della descrizione 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 il file pbiviz.json .

Per gestire il supporto delle descrizioni comando moderne della pagina del report, aggiungere la supportEnhancedTooltips proprietà all'oggetto tooltipsnel 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

Utils della descrizione comando

Personalizzare le descrizioni comando in Power BI

Creare descrizioni comando basate sulle pagine del report in Power BI Desktop