Freigeben über

Fügen Sie Tooltips zu Ihren Power BI-Visualisierungen hinzu

QuickInfos sind eine elegante Methode zum Bereitstellen zusätzlicher Kontextinformationen und Details zu Datenpunkten in einem Visual. Die Tooltip-API für Power BI kann die folgenden Interaktionen verarbeiten:

  • Anzeigen eines Tooltips
  • Ausblenden einer QuickInfo
  • Verschieben einer QuickInfo

Eine QuickInfo kann als Textelement mit einem Titel, einem Wert in einer bestimmten Farbe und Deckkraft und einer Gruppe von Koordinaten angezeigt werden. Diese Daten werden anschließend der API zur Verfügung gestellt und vom Power BI-Host auf dieselbe Weise gerendert wie QuickInfos für native Visuals.

Sie können den Stil Ihrer QuickInfos ändern oder Drillaktionen hinzufügen, indem Sie das Feature für moderne QuickInfos aktivieren.

Auf dem folgenden Screenshot ist eine QuickInfo in einem Beispielbalkendiagramm zu sehen:

Screenshot: QuickInfos in einem Beispielbalkendiagramm

Das obige Tooltip-Bild zeigt eine Kategorie und einen Wert für einen einzelnen Balken. Sie können die QuickInfo so erweitern, dass mehrere Werte angezeigt werden.

Verwalten von Tooltips

Sie können die QuickInfos in Ihrem Visual über die ITooltipService-Schnittstelle verwalten. ITooltipService benachrichtigt den Host darüber, dass eine QuickInfo angezeigt, entfernt oder verschoben werden muss.

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

Ihr Visual sollte Mausereignisse darin erkennen und nach Bedarf die Delegaten show(), move() oder hide() mit dem richtigen Inhalt in den options-QuickInfo-Objekten aufrufen. Durch TooltipShowOptions und TooltipHideOptions wird wiederum definiert, was bei Auftreten dieser Ereignisse angezeigt wird und wie sich die QuickInfo verhält.

Beim Aufrufen dieser Methoden spielen Benutzerereignisse wie Mausbewegungen und Touchereignisse eine Rolle, daher empfiehlt es sich, Listener für diese Ereignisse zu erstellen. Diese rufen dann ihrerseits die TooltipService-Elemente auf. Im folgenden Beispiel wird in einer Klasse namens TooltipServiceWrapper aggregiert.

Die TooltipServiceWrapper-Klasse

Die Grundidee dieser Klasse ist, dass sie die Instanz von TooltipService enthält, D3-Mausereignisse auf relevanten Elementen überwacht und dann bei Bedarf das Element show() oder hide() aufruft.

Die Klasse enthält und verwaltet relevante Zustands- und Logikinformationen für diese Ereignisse, die hauptsächlich auf die Verknüpfung mit dem zugrunde liegenden D3-Code ausgerichtet sind. Die Verknüpfung und Konvertierung von D3-Code wird in diesem Artikel nicht behandelt.

Der Beispielcode in diesem Artikel basiert auf dem Visual SampleBarChart. Sie können den Quellcode in barChart.ts untersuchen.

Erstellen einer TooltipServiceWrapper-Instanz

Der Konstruktor des Balkendiagramms verfügt jetzt über einen TooltipServiceWrapper-Member, der im Konstruktor mit der tooltipService-Hostinstanz instanziiert wird.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

Die TooltipServiceWrapper-Klasse hält die tooltipService-Instanz und dient zugleich als D3-Stammelement der Visual- und Touchparameter.

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

Der einzige Einstiegspunkt, über den diese Klasse Ereignislistener registrieren kann, ist die addTooltip-Methode.

Die addTooltip-Methode

        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.Selection<Element>: Die D3-Elemente, über die QuickInfos verarbeitet werden.
  • getTooltipInfoDelegate: (args: TooltipEventArgs <T>) => VisualTooltipDataItem[]: Der Delegat zum Aufpopulieren des QuickInfo-Inhalts (was angezeigt werden soll) pro Kontext.
  • getDataPointIdentity: (args: TooltipEventArgs <T>) = > ISelectionId: Der Delegat zum Abrufen der Datenpunkt-ID (in diesem Beispiel nicht verwendet).
  • reloadTooltipDataOnMouseMove? boolean: ein boolescher Wert, der angibt, ob die QuickInfo-Daten während eines MouseMove-Ereignisses aktualisiert werden (in diesem Beispiel nicht verwendet).

Wie Sie sehen, wird addTooltip ohne Aktion beendet, wenn tooltipService deaktiviert ist oder keine Auswahl vorliegt.

Rufen Sie die Methode „show“ auf, um einen Tooltipp anzuzeigen.

Die addTooltip-Methode lauscht auf das D3-mouseover-Ereignis, wie im folgenden Code gezeigt wird:

        ...
        ...
        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: Extrahiert den Kontext aus den ausgewählten D3-Elementen in tooltipEventArgs. Die Koordinaten werden ebenfalls berechnet.
  • getTooltipInfoDelegate: Anschließend wird der Tooltip-Inhalt aus den tooltipEventArgs erstellt. Dies ist ein Rückruf an die BarChart-Klasse, da es sich hier um die Logik des Visuals handelt. Dies ist der tatsächliche Textinhalt, der in der QuickInfo angezeigt wird.
  • getDataPointIdentity: in diesem Beispiel nicht verwendet.
  • this.visualHostTooltipService.show: Der Aufruf zum Anzeigen der QuickInfo

Weitere praktische Informationen finden Sie in den Beispielen für das mouseout-Ereignis und das mousemove-Ereignis.

Weitere Informationen finden Sie im SampleBarChart-Visualrepository.

Füllen des Tooltip-Inhalts mithilfe der getTooltipData-Methode

Die BarChart-Klasse wurde mit einem getTooltipData-Member hinzugefügt, durch den category, value und color des Datenpunkts einfach in ein VisualTooltipDataItem[]-Element extrahiert wird.

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

In der vorangehenden Implementierung ist der header-Member eine Konstante. Er kann jedoch auch für komplexere Implementierungen verwendet werden, die dynamische Werte erfordern. Sie können VisualTooltipDataItem[] mit mehreren Elementen auffüllen, um der QuickInfo mehrere Zeilen hinzuzufügen. Dies kann in Visuals wie gestapelten Balkendiagrammen nützlich sein, in denen QuickInfos Daten aus mehreren Datenpunkten anzeigen können.

Aufrufen der addTooltip-Methode

Der letzte Schritt besteht darin, die addTooltip-Methode aufzurufen, wenn sich die Daten ändern. Dieser Aufruf findet in der BarChart.update()-Methode statt. Durch einen Aufruf wird die Auswahl aller bar-Elemente überwacht und wie oben erwähnt nur BarChart.getTooltipData() übergeben.

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

Hinzufügen der Unterstützung von QuickInfos zur Berichtsseite

Gehen Sie wie folgt vor, um QuickInfo-Unterstützung für Berichtsseiten (die Möglichkeit, QuickInfos im Formatierungsbereich der Berichtsseite zu bearbeiten) hinzuzufügen: Ergänzen Sie in der Datei capabilities.json ein tooltips-Objekt.

Zum Beispiel:

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

Anschließend können Sie die QuickInfos im Formatierungsbereich der Berichtsseite definieren.

  • supportedTypes: Die QuickInfo-Konfiguration, die vom Visual unterstützt und in den Feldern verwendet wird
    • default: Gibt an, ob die „automatische“ Bindung von QuickInfos über das Datenfeld unterstützt wird.
    • canvas: Gibt an, ob Tooltips für Berichtsseiten unterstützt werden.
  • roles: Optionale Einstellung, mit der festgelegt wird, welche Datenrollen an die ausgewählte QuickInfo-Option im Bereich „Felder“ gebunden werden sollen.

Screenshot: QuickInfo-Dialogfeld der Berichtsseite

Weitere Informationen finden Sie unter Nutzungsrichtlinien für QuickInfos auf Berichtsseiten.

Der Power BI-Host ruft zuerst ITooltipService.Show(options: TooltipShowOptions) oder ITooltipService.Move(options: TooltipMoveOptions) auf, um die QuickInfo für die Berichtsseite anzuzeigen. Anschließend wird selectionId genutzt (identities-Eigenschaft des vorangehenden options-Arguments). selectionId sollte die ausgewählten Daten (Kategorie, Reihe usw.) des Elements darstellen, auf das Sie gezeigt haben, um von der QuickInfo abgerufen werden zu können.

So wird die selectionId an Aufrufe zur Anzeige eines Tooltips gesendet, was im folgenden Codebeispiel gezeigt wird:

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

Hinzufügen der Unterstützung von modernen QuickInfos zur Berichtsseite

Ab API-Version 3.8.3 können Sie auch moderne visuelle QuickInfos erstellen. Moderne visuelle QuickInfos fügen Ihren QuickInfos Datenpunkt-Drillaktionen hinzu und aktualisieren die Formatvorlage, um sie an Ihr Berichtsdesign anzupassen. Um herauszufinden, welche Version Sie verwenden, überprüfen Sie die apiVersion in der Datei pbiviz.json.

Screenshot, das eine moderne Tooltip zeigt.

Um die Unterstützung moderner QuickInfos für Berichtsseiten zu verwalten, fügen Sie dem tooltips-Objekt in der Datei capabilities.json die Eigenschaft supportEnhancedTooltips hinzu.

Zum Beispiel:

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

Im SampleBarChart-Code sehen Sie ein Beispiel für die Verwendung des modernen Tooltips-Features.

Hinweis

Das Hinzufügen dieses Features zur Datei capabilities.json gibt dem Benutzer die Möglichkeit, es für den Bericht zu aktivieren. Beachten Sie, dass der Benutzer das moderne QuickInfo-Feature noch in den Berichtseinstellungen aktivieren muss.

Zugehöriger Inhalt

  • Last updated on