Del via

Føj værktøjstip til dine Power BI-visualiseringer

  • Artikel

Værktøjstip er en elegant måde at give mere kontekstafhængige oplysninger og detaljer om datapunkter på en visualisering. Power BI-værktøjstip-API'en kan håndtere følgende interaktioner:

  • Vis et værktøjstip.
  • Skjul et værktøjstip.
  • Flyt et værktøjstip.

Værktøjstip kan vise et tekstelement med en titel, en værdi i en given farve og uigennemsigtighed ved et angivet sæt koordinater. Disse data leveres til API'en, og Power BI-værten gengiver dem på samme måde, som de gengiver værktøjstip for oprindelige visualiseringer.

Du kan ændre typografien for dine værktøjstip eller tilføje detaljeudledningshandlinger ved at aktivere funktionen moderne værktøjstip .

På følgende billede vises et værktøjstip i et eksempel på et liggende søjlediagram:

Screenshot that shows sample bar chart tooltips.

Billedet af ovenstående værktøjstip illustrerer en enkelt søjlekategori og -værdi. Du kan udvide værktøjstippet for at få vist flere værdier.

Administrer værktøjstip

Du kan administrere værktøjstip i din visualisering via grænsefladen ITooltipService . ITooltipService giver værten besked om, at et værktøjstip skal vises, fjernes eller flyttes.

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

Din visualisering skal registrere musehændelser i visualiseringen og kalde stedfortræderne show(), move()og hide() efter behov med det relevante indhold udfyldt i værktøjstippets options objekter. TooltipShowOptions og TooltipHideOptions derefter definere, hvad der skal vises, og hvordan de skal fungere i disse hændelser.

Kald af disse metoder omfatter brugerhændelser, f.eks. musebevægelser og berøringshændelser, så det er en god idé at oprette lyttere til disse hændelser, som igen kalder TooltipService medlemmerne. I følgende eksempel samles i en klasse kaldet TooltipServiceWrapper.

Klassen TooltipServiceWrapper

Den grundlæggende idé bag denne klasse er at holde forekomsten af TooltipService, lytte efter D3-musehændelser over relevante elementer og derefter foretage kald til show() og hide() elementerne, når det er nødvendigt.

Klassen indeholder og administrerer enhver relevant tilstand og logik for disse hændelser, som hovedsageligt er gearet til at arbejde sammen med den underliggende D3-kode. D3-grænsefladen og -konverteringen er ikke omfattet af denne artikel.

Eksempelkoden i denne artikel er baseret på visualiseringen SampleBarChart. Du kan undersøge kildekoden i barChart.ts.

Opret TooltipServiceWrapper

Søjlediagramkonstruktøren har nu et TooltipServiceWrapper medlem, som instantieres i konstruktøren med værtsforekomsten tooltipService .

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

Klassen TooltipServiceWrapper indeholder tooltipService forekomsten, også som rod-D3-elementet i visualiseringen og berøringsparametre.

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

Det enkelte indgangspunkt for denne klasse til registrering af addTooltip lyttefunktioner til hændelser er metoden .

Metoden 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. Markeringselement<>: De d3-elementer, som værktøjstip håndteres over.
  • getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: Stedfortræderen for udfyldelse af indholdet af værktøjstippet (hvad der skal vises) pr. kontekst.
  • getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: Stedfortræderen til hentning af datapunkt-id'et (bruges ikke i dette eksempel).
  • reloadTooltipDataOnMouseMove? boolesk: En boolesk værdi, der angiver, om værktøjstippets data skal opdateres under en MouseMove-hændelse (bruges ikke i dette eksempel).

Som du kan se, afsluttes uden handling, hvis tooltipService er deaktiveret, addTooltip eller der ikke er noget reelt valg.

Kald metoden show for at få vist et værktøjstip

Metoden addTooltip lytter derefter til D3-hændelsen mouseover , som vist i følgende kode:

        ...
        ...
        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: Udtrækker konteksten fra de D3-valgte elementer til et værktøjstipEventArgs. Koordinaterne beregnes også.
  • getTooltipInfoDelegate: Den bygger derefter indholdet af værktøjstippet fra tooltipEventArgs. Det er et tilbagekald til BarChart-klassen, fordi det er visualiseringens logik. Det er det faktiske tekstindhold, der skal vises i værktøjstippet.
  • getDataPointIdentity: Bruges ikke i dette eksempel.
  • this.visualHostTooltipService.show: Kaldet til at vise værktøjstippet.

Du kan finde yderligere håndtering i eksemplet for mouseout og mousemove -hændelser.

Du kan få flere oplysninger i lageret med SampleBarChart-visualiseringen.

Udfyld indholdet af værktøjstippet ved hjælp af metoden getTooltipData

Klassen BarChart blev tilføjet med et getTooltipData medlem, som ganske enkelt udtrækker categorydatapunktet , valueog color til et VisualTooltipDataItem[]-element.

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

I den foregående implementering header er medlemmet konstant, men du kan bruge det til mere komplekse implementeringer, som kræver dynamiske værdier. Du kan udfylde VisualTooltipDataItem[] med mere end ét element, hvilket føjer flere linjer til værktøjstippet. Det kan være nyttigt i visualiseringer, f.eks. stablede liggende søjlediagrammer, hvor værktøjstippet kan vise data fra mere end et enkelt datapunkt.

Kald metoden addTooltip

Det sidste trin er at kalde addTooltip metoden, når de faktiske data kan ændres. Dette kald finder sted i BarChart.update() metoden . Der foretages et kald for at overvåge valget af alle "søjleelementer" og kun BarChart.getTooltipData()overføre , som tidligere nævnt.

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

Føj understøttelse af værktøjstip til rapportsiden

Hvis du vil tilføje understøttelse af værktøjstip til rapportsider (muligheden for at ændre værktøjstip i formatruden på rapportsiden), skal du tilføje et tooltipsobjekt i filen capabilities.json .

Eksempler:

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

Du kan derefter definere værktøjstip fra ruden Formatering på rapportsiden.

  • supportedTypes: Den konfiguration af værktøjstip, der understøttes af visualiseringen og afspejles i feltoversigten.
    • default: Angiver, om binding af "automatiske" værktøjstip via datafeltet understøttes.
    • canvas: Angiver, om værktøjstip til rapportsider understøttes.
  • roles: (Valgfrit) Når den er defineret, får den besked om, hvilke dataroller der bindes til den valgte indstilling for værktøjstip i feltoversigten.

Screenshot that shows the Report page tooltip dialog.

Du kan få flere oplysninger under Retningslinjer for brug af værktøjstip til rapportsider.

Hvis du vil have vist værktøjstippet til rapportsiden, bruger det selectionId (identities egenskaben for det foregående options argument, når Power BI-værten kalder ITooltipService.Show(options: TooltipShowOptions) eller ITooltipService.Move(options: TooltipMoveOptions)). For at blive hentet af værktøjstippet skal SelectionId repræsentere de valgte data (kategori, serie osv.) for det element, du pegede på.

Et eksempel på, hvordan selectionId sendes til visningskald for værktøjstip, vises i følgende kode:

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

Føj understøttelse af moderne værktøjstip til rapportsiden

Fra API version 3.8.3 kan du også oprette moderne værktøjstip til visualiseringer. Moderne værktøjstip til visualiseringer føjer datapunktudledningshandlinger til dine værktøjstip og opdaterer typografien, så den passer til dit rapporttema. Du kan finde ud af, hvilken version du bruger, ved at se apiVersion i filen pbiviz.json .

Screenshot that shows a modern tooltip.

Hvis du vil administrere understøttelse af moderne værktøjstip til rapportsider, skal du føje supportEnhancedTooltips egenskaben til tooltipsobjektet i filen capabilities.json .

Eksempler:

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

Se et eksempel på den moderne funktion værktøjstip, der bruges i SampleBarChart-koden .

Bemærk

Hvis du føjer denne funktion til filen capabilities.json , får brugeren mulighed for at aktivere denne funktion for rapporten. Vær opmærksom på, at brugeren stadig skal aktivere den moderne værktøjstipfunktion i rapportindstillingerne.

Relateret indhold

Hjælpeprogrammer til værktøjstip

Tilpas værktøjstip i Power BI

Opret værktøjstip baseret på rapportsider i Power BI Desktop