Share via

Knopinfo toevoegen aan uw Power BI-visuals

Knopinfo zijn een elegante manier om meer contextuele informatie en details te bieden aan datapunten in een visual. De API voor Power BI-tooltips kan de volgende interacties verwerken:

  • Knopinfo weergeven.
  • Knopinfo verbergen.
  • Tooltip verplaatsen.

Tooltips kunnen een tekstueel element weergeven met een titel, een waarde in een bepaalde kleur en opaciteit op een opgegeven set coördinaten. Deze gegevens worden aan de API verstrekt en de Power BI-host geeft deze op dezelfde manier weer als knopinfo voor systeemeigen visuals.

U kunt de stijl van uw knopinfo wijzigen of booracties toevoegen door de moderne functie voor knopinfo in te schakelen.

In de volgende afbeelding ziet u een tooltip in een voorbeeldstaafdiagram.

Schermopname met voorbeeldknopinfo voor staafdiagrammen.

In de bovenstaande knopinfoafbeelding ziet u een categorie met één staaf en een waarde. U kunt de knopinfo uitbreiden om meerdere waarden weer te geven.

Knopinfo beheren

U kunt de knopinfo in uw visual beheren via de ITooltipService interface. ITooltipService informeert de host dat een tooltip moet worden weergegeven, verwijderd of verplaatst.

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

Uw visual moet muisgebeurtenissen in de visual detecteren en de show(), move()en hide() gemachtigden, indien nodig, aanroepen met de juiste inhoud die is ingevuld in de knopinfoobjecten options . TooltipShowOptions en TooltipHideOptions definieer op zijn beurt wat u wilt weergeven en hoe u zich moet gedragen in deze gebeurtenissen.

Het aanroepen van deze methoden omvat gebruikersevenementen zoals muisbewegingen en aanraakevenementen, dus het is een goed idee om listeners te maken voor deze gebeurtenissen, waardoor de TooltipService leden op hun beurt worden aangeroepen. Het volgende voorbeeld wordt samengevoegd in een klasse met de naam TooltipServiceWrapper.

De klasse TooltipServiceWrapper

Het basisidee achter deze klasse is het beheren van het exemplaar van de TooltipService, luisteren naar D3-muisgebeurtenissen over relevante elementen, en vervolgens de oproepen naar show() en hide() voor de elementen te maken wanneer nodig.

De klasse bevat en beheert alle relevante status en logica voor deze gebeurtenissen, die voornamelijk zijn gericht op communicatie met de onderliggende D3-code. De D3-communicatie en -conversie valt buiten het bereik van dit artikel.

De voorbeeldcode in dit artikel is gebaseerd op de visual SampleBarChart. U kunt de broncode in barChart.ts onderzoeken.

TooltipServiceWrapper maken

De balkdiagramconstructor heeft nu een TooltipServiceWrapper lid, dat in de constructor wordt geïnstantieerd met het hostexemplaar tooltipService.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

De TooltipServiceWrapper klasse bevat de tooltipService instantie, en fungeert ook als het D3 hoofdelement van de visuele en aanraakparameters.

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

Het enige toegangspunt voor deze klasse voor het registreren van gebeurtenislisteners is de addTooltip methode.

De methode 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;
            }
        ...
        ...
        }
  • selectie: d3.Selectie-element<>: De d3-elementen waarover tooltips worden verwerkt.
  • getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: De gemachtigde voor het vullen van de inhoud van knopinfo (wat moet worden weergegeven) per context.
  • getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: de gemachtigde voor het ophalen van de gegevenspunt-id (ongebruikt in dit voorbeeld).
  • reloadTooltipDataOnMouseMove? Booleaanse waarde: Een Booleaanse waarde die aangeeft of de knopinfogegevens moeten worden vernieuwd tijdens een MouseMove-gebeurtenis (ongebruikt in dit voorbeeld).

Zoals u kunt zien, addTooltip wordt afgesloten zonder actie als de tooltipService optie is uitgeschakeld of als er geen echte selectie is.

Roep de 'show'-methode aan om een tooltip weer te geven.

De addTooltip methode luistert vervolgens naar de D3-gebeurtenis mouseover , zoals wordt weergegeven in de volgende 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: Haalt de context van de geselecteerde D3-elementen naar een tooltipEventArgs. De coördinaten worden ook berekend.
  • getTooltipInfoDelegate: Het bouwt dan de inhoud van de tooltips uit de tooltipEventArgs. Het is een callback naar de BarChart-klasse, omdat het de logica van de visual is. Het is de daadwerkelijke tekst die moet worden weergegeven in de tooltip.
  • getDataPointIdentity: Ongebruikt in dit voorbeeld.
  • this.visualHostTooltipService.show: De aanroep om de tooltip weer te geven.

Aanvullende verwerking vindt u in het voorbeeld voor mouseout en mousemove gebeurtenissen.

Voor meer informatie, zie de visuele opslagplaats SampleBarChart.

De inhoud van de knopinfo vullen met de methode getTooltipData

De BarChart-klasse is toegevoegd met een getTooltipData-lid, waarmee eenvoudig de category, value, en color van het gegevenspunt worden geëxtraheerd in een VisualTooltipDataItem[]-element.

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

In de voorgaande implementatie is het header lid constant, maar u kunt het gebruiken voor complexere implementaties, waarvoor dynamische waarden zijn vereist. U kunt het VisualTooltipDataItem[] met meer dan één element vullen, waardoor meerdere regels aan de knopinfo worden toegevoegd. Het kan handig zijn in visuals, zoals gestapelde staafdiagrammen, waarbij de tooltip gegevens van meer dan één gegevenspunt kan weergeven.

De methode addTooltip aanroepen

De laatste stap is het aanroepen van de addTooltip methode wanneer de werkelijke gegevens kunnen veranderen. Deze aanroep vindt plaats in de BarChart.update() methode. Er wordt een aanroep gedaan om de selectie van alle 'staaf'-elementen te controleren, waarbij alleen de BarChart.getTooltipData(), zoals eerder vermeld, wordt doorgegeven.

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

Ondersteuning voor tooltips toevoegen aan de rapportpagina

Als u knopinfo voor rapportpagina's wilt toevoegen (de mogelijkheid om knopinfo te wijzigen in het opmaakvenster van de rapportpagina), voegt u een tooltipsobject toe aan het capabilities.json-bestand .

Voorbeeld:

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

Vervolgens kunt u de knopinfo definiëren vanuit het opmaakvenster van de rapportpagina.

  • supportedTypes: De tooltipconfiguratie die door de visual wordt ondersteund en goed wordt weergegeven in de velden.
    • default: Geeft aan of de 'automatische' tooltipsbinding via het gegevensveld wordt ondersteund.
    • canvas: Hiermee geeft u op of de knopinfo voor de rapportpagina wordt ondersteund.
  • roles: (Optioneel) Nadat deze is gedefinieerd, geeft deze aan welke gegevensrollen zijn gebonden aan de geselecteerde knopinfooptie in de velden.

Schermopname die het tooltip-dialoogvenster van de rapportpagina toont.

Voor meer informatie, zie richtlijnen voor het gebruik van knopinfo op rapportpagina's.

Als u de knopinfo voor de rapportpagina wilt weergeven, wordt na het aanroepen van de Power BI-host ITooltipService.Show(options: TooltipShowOptions) of ITooltipService.Move(options: TooltipMoveOptions) de selectionId (de identities-eigenschap van het voorgaande options-argument) gebruikt. Om opgehaald te worden door de tooltip, moet SelectionId de geselecteerde gegevens (categorie, reeks, enzovoort) van het item zijn dat u aanwijst.

Een voorbeeld van het verzenden van de selectionId naar weergaveaanroepen voor knopinfo wordt weergegeven in de volgende code:

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

Ondersteuning voor moderne knopinfo toevoegen aan de rapportpagina

Vanaf API-versie 3.8.3 kunt u ook moderne visuele tooltips maken. Moderne visuele tooltips voegen drillacties voor datapunten toe aan uw tooltips, en de stijl wordt bijgewerkt zodat deze overeenkomt met het rapportthema. Als u wilt achterhalen welke versie u gebruikt, controleert u het apiVersion bestand in het pbiviz.json .

Schermopname die een moderne tooltip toont.

Als u de ondersteuning voor moderne knopinfo voor rapportpagina's wilt beheren, voegt u de supportEnhancedTooltips eigenschap toe aan het tooltipsobject in het capabilities.json-bestand .

Voorbeeld:

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

Bekijk een voorbeeld van de moderne knopinfofunctie die wordt gebruikt in de SampleBarChart-code .

Notitie

Als u deze functie toevoegt aan het capabilities.json-bestand , heeft de gebruiker de mogelijkheid om deze functie voor het rapport in te schakelen. Houd er rekening mee dat de gebruiker nog steeds de moderne knopinfofunctie moet inschakelen in de rapportinstellingen.

Gerelateerde inhoud

  • Last updated on