Share via

Knopinfo toevoegen aan uw Power BI-visuals

  • Artikel

Knopinfo is een elegante manier om meer contextuele informatie en details te bieden aan gegevenspunten in een visual. De API voor power BI-knopinfo kan de volgende interacties verwerken:

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

Knopinfo kan een tekstueel element weergeven met een titel, een waarde in een bepaalde kleur en dekking 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 knopinfo in een voorbeeld van een staafdiagram:

Screenshot that shows sample bar chart tooltips.

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 hiermee wordt de host op de hoogte gebracht dat knopinfo 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 houden van het exemplaar van de TooltipService, luisteren naar D3-muisgebeurtenissen over relevante elementen en vervolgens de aanroepen naar show() en hide() de elementen wanneer dat nodig is.

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 staafdiagramconstructor heeft nu een TooltipServiceWrapper lid dat wordt geïnstantieerd in de constructor met het hostexemplaren tooltipService .

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

De TooltipServiceWrapper klasse bevat het tooltipService exemplaar, ook als het hoofdelement D3 van de visual 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 over welke knopinfo wordt 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.

De weergavemethode aanroepen om knopinfo 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: Extraheert de context van de geselecteerde D3-elementen in een tooltipEventArgs. De coördinaten worden ook berekend.
  • getTooltipInfoDelegate: vervolgens wordt de inhoud van de knopinfo opgebouwd uit de tooltipEventArgs. Het is een callback naar de BarChart-klasse, omdat het de logica van de visual is. Het is de werkelijke tekstinhoud die moet worden weergegeven in de knopinfo.
  • getDataPointIdentity: Ongebruikt in dit voorbeeld.
  • this.visualHostTooltipService.show: De aanroep om de knopinfo weer te geven.

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

Zie de visualopslagplaats SampleBarChart voor meer informatie.

De inhoud van de knopinfo vullen met de methode getTooltipData

De BarChart-klasse is toegevoegd met een getTooltipData lid, waarmee het gegevenspunt valuecolor eenvoudigweg wordt geëxtraheerd categorynaar 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 knopinfo mogelijk gegevens van meer dan één gegevenspunt weergeeft.

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 knopinfo 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 bestand capabilities.json .

Bijvoorbeeld:

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

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

  • supportedTypes: De configuratie van knopinfo die wordt ondersteund door de visual en wordt weergegeven in de velden.
    • default: Hiermee geeft u op of de 'automatische' knopinfobinding 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.

Screenshot that shows the Report page tooltip dialog.

Zie de gebruiksrichtlijnen voor knopinfo voor rapportpagina's voor meer informatie.

Als u de knopinfo voor de rapportpagina wilt weergeven nadat de Power BI-host wordt aanroepen ITooltipService.Show(options: TooltipShowOptions) of ITooltipService.Move(options: TooltipMoveOptions), wordt de selectionId (identities eigenschap van het voorgaande options argument) gebruikt. Als u wilt worden opgehaald met de knopinfo, moet SelectionId de geselecteerde gegevens (categorie, reeks, enzovoort) van het item vertegenwoordigen 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

Vanuit API-versie 3.8.3 kunt u ook moderne visuele knopinfo maken. Moderne visuele knopinfo voegt drillacties voor gegevenspunten toe aan uw knopinfo en werk de stijl bij zodat deze overeenkomt met het rapportthema. Als u wilt weten welke versie u gebruikt, controleert u het apiVersionbestand pbiviz.json .

Screenshot that shows a modern tooltip.

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

Bijvoorbeeld:

{
    "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 bestand capabilities.json , heeft de gebruiker de mogelijkheid om deze functie in te schakelen voor het rapport. Houd er rekening mee dat de gebruiker nog steeds de moderne knopinfofunctie moet inschakelen in de rapportinstellingen.

Gerelateerde inhoud

Hulpmiddelen voor knopinfo

Knopinfo aanpassen in Power BI

Knopinfo maken op basis van rapportpagina's in Power BI Desktop