Udostępnij za pośrednictwem

Dodawanie etykietek narzędzi do wizualizacji usługi Power BI

  • Artykuł

Etykietki narzędzi to elegancki sposób dostarczania bardziej kontekstowych informacji i szczegółów punktom danych w 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.

Etykietki narzędzi mogą wyświetlać element tekstowy z tytułem, wartością w danym kolorze i nieprzezroczystością w określonym zestawie współrzędnych. Te dane są dostarczane do interfejsu API, a host usługi Power BI renderuje je w taki sam sposób, jak w przypadku wizualizacji natywnych.

Możesz zmienić styl etykietek narzędzi lub dodać akcje przechodzenia do szczegółów, włączając funkcję nowoczesnych etykietek narzędzi.

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

Zrzut ekranu przedstawiający przykładowe etykietki narzędzi wykresu słupkowego.

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

Zarządzanie etykietkami narzędzi

Etykietki narzędzi można zarządzać 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 wizualizacji i w razie potrzeby wywoływać show()delegaty , move()i hide() z odpowiednią zawartością wypełniona w obiektach etykietki options narzędzi. TooltipShowOptions z TooltipHideOptions kolei zdefiniuj, co ma być wyświetlane i jak zachowywać się w tych zdarzeniach.

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

Klasa TooltipServiceWrapper

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

Klasa przechowuje wszelkie istotne stany i logikę dla tych zdarzeń i zarządza nimi, które są w większości wyposażone w interfacing przy użyciu bazowego kodu 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 TooltipServiceWrapper członkowski, który jest tworzone w konstruktorze z wystąpieniem hosta tooltipService .

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

Klasa TooltipServiceWrapper przechowuje tooltipService wystąpienie, również jako element główny D3 parametrów wizualizacji i dotyku.

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

Pojedynczy punkt wejścia dla tej klasy do rejestrowania odbiorników zdarzeń jest addTooltip metodą.

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, do których są obsługiwane 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 odświeżyć dane etykietki narzędzia podczas zdarzenia MouseMove (nieużywane w tym przykładzie).

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

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

Następnie addTooltip metoda 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 wywołanie zwrotne do klasy BarChart, ponieważ jest to logika wizualizacji. 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 mouseout zdarzeń i mousemove .

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

Wypełnianie zawartości etykietki narzędzia metodą getTooltipData

Klasa BarChart została dodana z elementem getTooltipData członkowskim, który po prostu wyodrębnia categoryelement , valuei 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ć element VisualTooltipDataItem[] więcej niż jednym elementem, który dodaje 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 "słupka", przekazując tylko BarChart.getTooltipData()element , 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ę etykietek narzędzi strony raportu (możliwość modyfikowania etykietek narzędzi w okienku formatowania strony raportu), dodaj tooltips obiekt 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 strony raportu.

  • supportedTypes: Konfiguracja etykietki narzędzia obsługiwana przez wizualizację i odzwierciedlona w obszarze pól.
    • default: określa, czy jest obsługiwane powiązanie etykietek narzędzi "automatycznych" za pośrednictwem pola danych.
    • 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.

Zrzut ekranu przedstawiający okno dialogowe Etykietka narzędzia strony raportu.

Aby uzyskać więcej informacji, zobacz Wytyczne dotyczące użycia etykietek narzędzi strony 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 etykietki narzędzi wizualizacji dodają akcje przechodzenia do szczegółów punktu danych do etykietek narzędzi i zaktualizują styl tak, aby był zgodny z motywem raportu. Aby dowiedzieć się, której wersji używasz, sprawdź apiVersion plik pbiviz.json .

Zrzut ekranu przedstawiający nowoczesną etykietkę narzędzia.

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

Na przykład:

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

Zobacz przykład nowoczesnej funkcji etykietek narzędzi używanych w kodzie SampleBarChart .

Uwaga

Dodanie tej funkcji do pliku capabilities.json daje użytkownikowi możliwość włączenia tej funkcji dla raportu. Należy pamiętać , że użytkownik będzie nadal musiał włączyć funkcję nowoczesnej etykietki narzędzi w ustawieniach raportu.

Powiązana zawartość