Dela via

Lägga till knappbeskrivningar i dina visuella Power BI-objekt

  • Artikel

Knappbeskrivningar är ett elegant sätt att ge mer sammanhangsberoende information och information till datapunkter i ett visuellt objekt. API:et för Knappbeskrivningar i Power BI kan hantera följande interaktioner:

  • Visa en knappbeskrivning.
  • Dölj en knappbeskrivning.
  • Flytta en knappbeskrivning.

Knappbeskrivningar kan visa ett textelement med en rubrik, ett värde i en viss färg och opacitet vid en angiven uppsättning koordinater. Dessa data tillhandahålls till API:et och Power BI-värden renderar dem på samma sätt som de renderar knappbeskrivningar för interna visuella objekt.

Du kan ändra stilen på knappbeskrivningarna eller lägga till detaljgranskningsåtgärder genom att aktivera funktionen för moderna knappbeskrivningar .

Följande bild visar en knappbeskrivning i ett exempelstapeldiagram:

Screenshot that shows sample bar chart tooltips.

Ovanstående knappbeskrivningsbild illustrerar en enskild stapelkategori och ett värde. Du kan utöka knappbeskrivningen för att visa flera värden.

Hantera knappbeskrivningar

Du kan hantera knappbeskrivningarna i det visuella objektet via ITooltipService gränssnittet. ITooltipService meddelar värden att en knappbeskrivning måste visas, tas bort eller flyttas.

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

Ditt visuella objekt bör identifiera mushändelser i det visuella objektet och anropa ombuden show(), move()och hide() efter behov, med lämpligt innehåll i knappbeskrivningsobjekten options . TooltipShowOptions och TooltipHideOptions i sin tur definiera vad som ska visas och hur du ska bete dig i dessa händelser.

Att anropa dessa metoder omfattar användarhändelser som musrörelser och touchhändelser, så det är en bra idé att skapa lyssnare för dessa händelser, vilket i sin tur skulle anropa TooltipService medlemmarna. I följande exempel aggregeras i en klass med namnet TooltipServiceWrapper.

Klassen TooltipServiceWrapper

Den grundläggande idén bakom den här klassen är att hålla instansen TooltipServiceav , lyssna efter D3-mushändelser över relevanta element och sedan göra anropen till show() och hide() elementen när det behövs.

Klassen innehåller och hanterar alla relevanta tillstånd och logik för dessa händelser, som främst är inriktade på att samverka med den underliggande D3-koden. D3-gränssnittet och konverteringen ligger utanför omfånget för den här artikeln.

Exempelkoden i den här artikeln baseras på det visuella SampleBarChart-objektet. Du kan undersöka källkoden i barChart.ts.

Skapa TooltipServiceWrapper

Konstruktorn för stapeldiagram har nu en TooltipServiceWrapper medlem som instansieras i konstruktorn med värdinstansen tooltipService .

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

Klassen TooltipServiceWrapper innehåller instansen tooltipService , även som rot-D3-elementet i de visuella parametrarna och touchparametrarna.

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

Den enda startpunkten för den här klassen för att registrera händelselyssnare addTooltip är 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<>: D3-elementen som knappbeskrivningarna hanteras över.
  • getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: Ombudet för att fylla i knappbeskrivningsinnehållet (vad som ska visas) per kontext.
  • getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: Ombudet för att hämta datapunkts-ID (används inte i det här exemplet).
  • reloadTooltipDataOnMouseMove? booleskt värde: Ett booleskt värde som anger om knappbeskrivningsdata ska uppdateras under en MouseMove-händelse (används inte i det här exemplet).

Som du ser addTooltip avslutas utan åtgärd om den tooltipService är inaktiverad eller om det inte finns något verkligt val.

Anropa show-metoden för att visa en knappbeskrivning

Metoden addTooltip lyssnar sedan på D3-händelsen mouseover , enligt följande kod:

        ...
        ...
        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: Extraherar kontexten från de markerade D3-elementen till en tooltipEventArgs. Den beräknar även koordinaterna.
  • getTooltipInfoDelegate: Sedan skapas knappbeskrivningsinnehållet från tooltipEventArgs. Det är ett återanrop till klassen BarChart eftersom det är det visuella objektets logik. Det är det faktiska textinnehållet som ska visas i knappbeskrivningen.
  • getDataPointIdentity: Används inte i det här exemplet.
  • this.visualHostTooltipService.show: Anropet för att visa knappbeskrivningen.

Ytterligare hantering finns i exemplet för mouseout och mousemove händelser.

Mer information finns i den visuella lagringsplatsen SampleBarChart.

Fyll i knappbeskrivningsinnehållet med metoden getTooltipData

Klassen BarChart lades till med en getTooltipData medlem, som helt enkelt extraherar categorydatapunkten , valueoch color till ett VisualTooltipDataItem[]-element.

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

I föregående implementering header är medlemmen konstant, men du kan använda den för mer komplexa implementeringar, vilket kräver dynamiska värden. Du kan fylla i VisualTooltipDataItem[] med fler än ett element, vilket lägger till flera rader i knappbeskrivningen. Det kan vara användbart i visuella objekt, till exempel staplade stapeldiagram där knappbeskrivningen kan visa data från mer än en enda datapunkt.

Anropa metoden addTooltip

Det sista steget är att anropa addTooltip metoden när faktiska data kan ändras. Det här anropet BarChart.update() sker i -metoden. Ett anrop görs för att övervaka valet av alla "bar"-element, vilket endast BarChart.getTooltipData()skickar , som tidigare nämnts.

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

Lägga till stöd för knappbeskrivningar på rapportsidan

Om du vill lägga till stöd för knappbeskrivningar för rapportsidor (möjlighet att ändra knappbeskrivningar i formatfönstret på rapportsidan) lägger du till ett tooltipsobjekt i filen capabilities.json .

Till exempel:

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

Du kan sedan definiera knappbeskrivningarna från formateringsfönstret på rapportsidan.

  • supportedTypes: Knappbeskrivningskonfigurationen som stöds av det visuella objektet och återspeglas i fältbrunnarna.
    • default: Anger om bindning av automatiska knappbeskrivningar via datafältet stöds.
    • canvas: Anger om knappbeskrivningarna för rapportsidan stöds.
  • roles: (Valfritt) När den har definierats instrueras vilka dataroller som är bundna till det valda knappbeskrivningsalternativet i fältbrunn.

Screenshot that shows the Report page tooltip dialog.

Mer information finns i Användningsriktlinjer för rapportsidans knappbeskrivningar.

Om du vill visa knappbeskrivningen för rapportsidan, när Power BI-värden anropar ITooltipService.Show(options: TooltipShowOptions) eller ITooltipService.Move(options: TooltipMoveOptions)använder den egenskapen selectionId (identities för föregående options argument). För att hämtas med knappbeskrivningen ska SelectionId representera de markerade data (kategori, serier och så vidare) för det objekt som du hovrade över.

Ett exempel på hur du skickar selectionId till knappbeskrivningsvisningsanrop visas i följande kod:

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

Lägga till stöd för moderna knappbeskrivningar på rapportsidan

Från API version 3.8.3 kan du också skapa moderna visuella knappbeskrivningar. Moderna visuella knappbeskrivningar lägger till datapunktsteståtgärder i knappbeskrivningarna och uppdaterar formatmallen så att den matchar rapporttemat. Om du vill ta reda på vilken version du använder kontrollerar apiVersion du i filen pbiviz.json .

Screenshot that shows a modern tooltip.

Om du vill hantera stöd för moderna knappbeskrivningar för rapportsidan lägger du till supportEnhancedTooltipstooltipsegenskapen i objektet i filen capabilities.json.

Till exempel:

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

Se ett exempel på den moderna knappbeskrivningsfunktionen som används i SampleBarChart-koden .

Kommentar

Genom att lägga till den här funktionen i filen capabilities.json kan användaren aktivera den här funktionen för rapporten. Tänk på att användaren fortfarande måste aktivera den moderna knappbeskrivningsfunktionen i rapportinställningarna.

Relaterat innehåll

Knappbeskrivningsverktyg

Anpassa knappbeskrivningar i Power BI

Skapa knappbeskrivningar baserat på rapportsidor i Power BI Desktop