Přidání popisů do vizuálů Power BI

Popisy jsou elegantní způsob, jak poskytnout více kontextových informací a podrobností datovým bodům ve vizuálu. Rozhraní API popisů Power BI může zpracovávat následující interakce:

  • Zobrazení popisu
  • Skrytí popisu
  • Přesunutí popisu

Popisy dokážou na stanovených souřadnicích zobrazit textový prvek s nadpisem a hodnotou v určité barvě a s určitou průhledností. Tato data jsou poskytnuta rozhraní API a hostitel Power BI je vykreslí stejným způsobem jako v případě popisů nativních vizuálů.

Styl popisů můžete změnit nebo přidat akce procházení povolením moderní funkce popisů .

Následující obrázek znázorňuje popis v ukázkovém pruhovém grafu:

Sample bar chart tooltips

Obrázek výše uvedeného popisu znázorňuje jednu pruhovou kategorii a hodnotu. Popis můžete rozšířit tak, aby zobrazoval více hodnot.

Správa popisů

Popisy ve vizuálu ITooltipService můžete spravovat prostřednictvím rozhraní. ITooltipService upozorní hostitele, že je potřeba zobrazit, odebrat nebo přesunout popis.

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

Vizuál by měl naslouchat událostem myši ve vizuálu a podle potřeby volat show()move(), a hide() delegáty s odpovídajícím obsahem vyplněným v objektech popisuoptions. Objekty TooltipShowOptions a TooltipHideOptions pak definují, co se má zobrazit, a jak se při těchto událostech chovat.

Volání těchto metod zahrnuje události uživatelů, jako jsou pohyby myší a dotykové události, takže je vhodné vytvořit naslouchací procesy pro tyto události, které by zase vyvolaly TooltipService členy. Následující příklad agreguje ve třídě s názvem TooltipServiceWrapper.

Třída TooltipServiceWrapper

Základní myšlenkou této třídy je uložení instance TooltipService, naslouchání událostem myši D3 nad relevantními prvky a následné volání do show() a hide() elementů v případě potřeby.

Tato třída uchovává a řídí veškeré relevantní stavy a logiku těchto událostí, které se zaměřují hlavně na komunikaci přes rozhraní se základním kódem D3. Komunikací přes rozhraní D3 a souvisejícími převody se tento článek nezabývá.

Ukázkový kód v tomto článku je založený na vizuálu SampleBarChart. Zdrojový kód můžete prozkoumat v barChart.ts.

Vytvoření třídy TooltipServiceWrapper

Konstruktor pruhového grafu teď obsahuje člen TooltipServiceWrapper, jehož instance se vytvoří v konstruktoru s hostitelskou instancí tooltipService.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

Třída TooltipServiceWrapper uchovává instanci tooltipService – také jako kořenový prvek D3 pro parametry vizuálu a dotykové ovládání.

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

Tato třída má jediný vstupní bod, který umožňuje registraci naslouchacích procesů událostí, a jde o metodu 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;
            }
        ...
        ...
        }
  • výběr: d3. SelectionElement><: Prvky d3, u kterých jsou popisy zpracovávány.

  • getTooltipInfoDelegate: (args: TooltipEventArgsT<>) => VisualTooltipDataItem[]: Delegát pro naplnění obsahu popisu (co se má zobrazit) na kontext.

  • getDataPointIdentity: (args: TooltipEventArgsT<>) => ISelectionId: delegát pro načtení ID datového bodu (nevyužité v této ukázce).

  • reloadTooltipDataOnMouseMove? boolean: Logická hodnota, která udává, jestli se data popisu mají aktualizovat během události MouseMove (v této ukázce se nepoužívá)

Jak vidíte, addTooltip se ukončuje bez akce, pokud je položka tooltipService zakázaná nebo neexistuje žádný skutečný výběr.

Volání metody show pro zobrazení popisu

Metoda addTooltip dále naslouchá události D3 mouseover, jak ukazuje následující kód:

        ...
        ...
        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: Extrahuje kontext z prvků vybraných při události D3 do tooltipEventArgs. Zároveň vypočítá souřadnice.

  • getTooltipInfoDelegate: Pak z tooltipEventArgs sestaví obsah popisu. Jedná se o zpětné volání do třídy BarChart, protože jde o logiku vizuálu. To je skutečný textový obsah, který se má v popisu zobrazit.

  • getDataPointIdentity: V této ukázce se nepoužívá.

  • this.visualHostTooltipService.show: Volání pro zobrazení popisu

Další akce najdete v ukázce pro události mouseout a mousemove.

Další informace najdete v úložišti vizuálů pro SampleBarChart.

Dosazení obsahu popisu metodou getTooltipData

Třída BarChart byla přidána s členem getTooltipData, který jednoduše extrahuje category, value a color datového bodu do prvku VisualTooltipDataItem[].

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

V předchozí implementaci je člen header konstantní, můžete ho ale použít ve složitějších implementacích, které vyžadují dynamické hodnoty. Do VisualTooltipDataItem[] můžete dosadit více než jeden prvek, čímž do popisu přidáte více řádků. To může být užitečné ve vizuálech, jako jsou skládané pruhové grafy, kdy se v popisu mohou zobrazovat data z více než jednoho datového bodu.

Volání metody addTooltip

Posledním krokem je volání metody addTooltip, pokud se skutečná data mohou měnit. Toto volání probíhá v metodě BarChart.update(). Provede se volání, které monitoruje výběr všech „pruhových“ prvků, a předá se jen BarChart.getTooltipData(), jak je zmíněno dříve.

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

Přidání podpory popisů na stránku sestavy

Pokud chcete přidat podporu popisů stránky sestavy (možnost upravit popisy v podokně formátu stránky sestavy), přidejte tooltipsobjekt do souboru capabilities.json .

Například:

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

Potom můžete definovat popisy z podokna Formátování stránky sestavy.

  • supportedTypes: Konfigurace popisu podporovaná vizuálem a promítnutá do polí.

    • default: Určuje, jestli se podporuje „automatická“ vazba popisů přes datové pole.
    • canvas: Určuje, jestli se podporují popisy stránek sestavy.
  • roles: (Nepovinné) Po definování udává, jaké role dat jsou vázané k vybrané možnosti popisu také v polích.

Report page tooltip

Další informace najdete v pokynech k použití popisů stránek sestavy.

Aby hostitel Power BI zobrazil popis stránky sestavy, pak poté, co zavolá ITooltipService.Show(options: TooltipShowOptions) nebo ITooltipService.Move(options: TooltipMoveOptions), spotřebuje selectionId (vlastnost identities předchozího argumentu options). Aby ho popis mohl načíst, měl by prvek SelectionId představovat vybraná data (kategorie, řada atd.), položky, na kterou jste najeli myší.

Příklad odeslání prvku selectionId do volání pro zobrazení popisu je uvedený v následujícím kódu:

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

Přidání podpory moderních popisů na stránku sestavy

Z rozhraní API verze 3.8.3 můžete také vytvořit moderní vizuální popisy. Moderní vizuální popisy přidávají akce podrobné analýzy datových bodů do popisů a aktualizují styl tak, aby odpovídaly motivu sestavy.

modern tooltip

Pokud chcete spravovat podporu moderních popisů stránky sestavy, přidejte supportEnhancedTooltips vlastnost do objektutooltips v souboru capabilities.json.

Například:

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

Příklad moderní funkce popisů, která se používá v kódu SampleBarChart , si můžete prohlédnout.

Poznámka

Přidání této funkce do souboru capabilities.json uživateli umožní povolit tuto funkci pro sestavu. Mějte na paměti, že uživatel bude muset v nastavení sestavy povolit moderní funkci popisu .

Další kroky