Dodaj podpowiedzi do wizualizacji Power BI

Podpowiedzi to elegancki sposób dostarczania bardziej kontekstowych informacji i detali dla punktów danych na wizualizacji. Interfejs API etykietek narzędzi usługi Power BI może obsługiwać następujące interakcje:

• Pokaż etykietkę narzędzia.
• Ukryj etykietkę narzędzia.
• Przenieś etykietkę narzędzia.

Podpowiedzi mogą wyświetlać element tekstowy z tytułem, wartością w określonym kolorze i przezroczystością na podanych współrzędnych. Te dane są dostarczane do interfejsu API, a host Power BI renderuje je w taki sam sposób, jak renderuje podpowiedzi dla wizualizacji natywnych.

Możesz zmienić styl etykietek narzędzi lub dodać akcje zagłębiania się w detal, włączając funkcję nowoczesnych etykietek narzędzi.

Na poniższej ilustracji przedstawiono etykietkę narzędzia na przykładowym wykresie słupkowym:

Powyższy obraz podpowiedzi ilustruje pojedynczą kategorię i wartość paska. Tooltip można rozszerzyć, aby wyświetlić wiele wartości.

Zarządzanie podpowiedziami

Możesz zarządzać podpowiedziami w wizualizacji za pomocą interfejsu ITooltipService. ITooltipService powiadamia hosta, że etykietka narzędzia musi być wyświetlana, usuwana lub przenoszona.

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

Wizualizacja powinna wykrywać zdarzenia myszy w obrębie wizualizacji i, w razie potrzeby, wywoływać delegaty show(), move() i hide() z odpowiednią zawartością wypełnioną w obiektach etykiety narzędzia options. TooltipShowOptions i TooltipHideOptions z kolei zdefiniują, co ma być wyświetlane i jak mają się zachowywać w tych zdarzeniach.

Wywoływanie tych metod obejmuje zdarzenia użytkownika, takie jak ruchy myszy i zdarzenia dotykowe, dlatego dobrym pomysłem jest utworzenie nasłuchiwaczy dla tych zdarzeń, które z kolei wywołają TooltipService członków. Poniższy przykład agreguje w klasie o nazwie TooltipServiceWrapper.

Klasa TooltipServiceWrapper

Podstawową ideą tej klasy jest utrzymywanie wystąpienia TooltipService, nasłuchiwanie zdarzeń myszy D3 nad elementami odpowiednimi, a następnie wykonanie wywołań show() i hide() w razie potrzeby.

Klasa przechowuje wszelkie istotne stany i logikę dla tych zdarzeń i zarządza nimi, koncentrując się głównie na interfejsowaniu z bazowym kodem D3. Interfacing i konwersja D3 nie mieści się w zakresie tego artykułu.

Przykładowy kod w tym artykule jest oparty na wizualizacji SampleBarChart. Kod źródłowy można sprawdzić w barChart.ts.

Tworzenie elementu TooltipServiceWrapper

Konstruktor wykresu słupkowego ma teraz element członkowski TooltipServiceWrapper, który jest tworzony w konstruktorze wraz z wystąpieniem hosta tooltipService.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

Klasa TooltipServiceWrapper przechowuje instancję tooltipService, pełniąc również rolę elementu korzeniowego D3 parametrów wizualnych i dotykowych.

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

Pojedynczym punktem wejścia dla tej klasy do rejestrowania nasłuchiwaczy zdarzeń jest metoda addTooltip.

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

• wybór: d3.Selection<Element>: elementy d3, dla których obsługiwane są etykietki narzędzi.
• getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: Delegat do wypełniania zawartości etykietki narzędzia (co do wyświetlenia) dla kontekstu.
• getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: delegat pobierania identyfikatora punktu danych (nieużywany w tym przykładzie).
• reloadTooltipDataOnMouseMove? wartość logiczna: wartość logiczna wskazująca, czy należy odświeżyć dane podpowiedzi podczas zdarzenia MouseMove (niewykorzystywane w tym przykładzie).

Jak widać, addTooltip kończy działanie bez akcji, jeśli element tooltipService jest wyłączony lub nie dokonano rzeczywistego wyboru.

Wywoływanie metody show w celu wyświetlenia etykietki narzędzia

Metoda addTooltip następnie nasłuchuje zdarzenia D3 mouseover, jak pokazano w poniższym kodzie.

        ...
        ...
        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: wyodrębnia kontekst z wybranych elementów D3 do elementu tooltipEventArgs. Oblicza również współrzędne.
• getTooltipInfoDelegate: następnie tworzy zawartość etykietki narzędzia z elementu tooltipEventArgs. Jest to odwołanie do klasy BarChart, ponieważ jest to logika elementu wizualnego. Jest to rzeczywista zawartość tekstowa wyświetlana w etykietce narzędzia.
• getDataPointIdentity: Nieużywane w tym przykładzie.
• this.visualHostTooltipService.show: wywołanie w celu wyświetlenia etykietki narzędzia.

Dodatkową obsługę można znaleźć w przykładzie dla zdarzeń mouseout i mousemove.

Aby uzyskać więcej informacji, zobacz repozytorium wizualizacji SampleBarChart.

Wypełnij zawartość podpowiedzi za pomocą metody getTooltipData.

Klasa BarChart została dodana z członkowskim elementem getTooltipData, który po prostu wyodrębnia category, value i color punktu danych do elementu VisualTooltipDataItem[].

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

W poprzedniej implementacji element header członkowski jest stały, ale można go użyć do bardziej złożonych implementacji, które wymagają wartości dynamicznych. Możesz wypełnić VisualTooltipDataItem[] więcej niż jednym elementem, co doda wiele wierszy do etykietki narzędzia. Może to być przydatne w wizualizacjach, takich jak skumulowane wykresy słupkowe, w których etykietka narzędzia może wyświetlać dane z więcej niż jednego punktu danych.

Wywoływanie metody addTooltip

Ostatnim krokiem jest wywołanie addTooltip metody, gdy rzeczywiste dane mogą ulec zmianie. To wywołanie odbywa się w metodzie BarChart.update() . Wykonano wywołanie w celu monitorowania wyboru wszystkich elementów "bar", przekazując tylko BarChart.getTooltipData(), jak wspomniano wcześniej.

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

Dodawanie obsługi etykietek narzędzi do strony raportu

Aby dodać obsługę podpowiedzi strony raportu (możliwość modyfikacji podpowiedzi w okienku formatowania strony raportu), dodaj tooltipsobiekt w pliku capabilities.json.

Na przykład:

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

Następnie można zdefiniować etykietki narzędzi w okienku Formatowanie na stronie raportu.

• supportedTypes: Konfiguracja etykietki narzędzia obsługiwana przez wizualizację i odzwierciedlona w obszarze pól.
  • default: Określa, czy powiązanie etykiet narzędziowych "automatycznych" za pośrednictwem pola danych jest obsługiwane.
  • canvas: określa, czy etykietki narzędzi strony raportu są obsługiwane.
• roles: (Opcjonalnie) Po zdefiniowaniu powoduje, że role danych są powiązane z wybraną opcją etykietki narzędzia w obszarze pól.

Aby uzyskać więcej informacji, zapoznaj się z Wytycznymi dotyczącymi użycia wskazówek narzędziowych na stronie raportu.

Aby wyświetlić etykietkę narzędzia strony raportu, po wywołaniu ITooltipService.Show(options: TooltipShowOptions) hosta usługi Power BI lub ITooltipService.Move(options: TooltipMoveOptions), używa właściwości selectionId (identities właściwości poprzedniego options argumentu). Aby pobrać przez etykietkę narzędzia, SelectionId powinien reprezentować wybrane dane (kategoria, seria itd.) elementu, nad którym zatrzymano wskaźnik myszy.

Przykład wysyłania parametru selectionId do wywołań wyświetlania etykietki narzędzia jest wyświetlany w następującym kodzie:

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

Dodawanie obsługi nowoczesnych etykietek narzędzi do strony raportu

Z poziomu interfejsu API w wersji 3.8.3 można również tworzyć nowoczesne etykietki narzędzi wizualnych. Nowoczesne wizualne podpowiedzi dodają akcje drążenia punktu danych do swoich etykiet i aktualizują styl zgodnie z motywem raportu. Aby dowiedzieć się, której wersji używasz, sprawdź apiVersion plik pbiviz.json .

Aby zarządzać obsługą nowoczesnych etykietek narzędzi strony raportu, dodaj supportEnhancedTooltips właściwość do tooltipsobiektu w pliku capabilities.json .

Na przykład:

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

Zobacz przykład użycia nowoczesnej funkcji podpowiedzi w kodzie SampleBarChart.

Powiązana zawartość

• Narzędzia do podpowiedzi
• Dostosowywanie etykietek narzędzi w usłudze Power BI
• Tworzenie etykietek narzędzi na podstawie stron raportu w programie Power BI Desktop