Popisy ve vizuálech Power BI

Popisy jsou elegantní způsob, jak poskytnout další kontextové informace a podrobnosti datovým bodům ve vizuálu. Rozhraní API Power BI popisy dat dokáže zpracovat 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ů tlačítek můžete aktualizovat nebo můžete povolit moderní funkci popisů.

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

Popisy v ukázkovém pruhovém grafu

Výše uvedený obrázek popisu znázorňuje kategorii a hodnotu s jedním pruhem. Popis můžete rozšířit tak, aby se v nástroji zobrazuje více hodnot.

Správa popisů

Popisy ve vizuálu můžete spravovat prostřednictvím ITooltipService 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 delegáty , a s odpovídajícím obsahem naplněný v objektech show() move() hide() options Popis. Objekty TooltipShowOptions a TooltipHideOptions pak definují, co se má zobrazit, a jak se při těchto událostech chovat.

Protože volání těchto metod zahrnuje uživatelské události, jako jsou pohyby myši nebo dotykové události, je vhodné pro tyto události vytvořit naslouchací procesy, které budou následně vyvolávat členy TooltipService. 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 uchovat instanci , naslouchat událostem myši D3 nad relevantními prvky a v případě potřeby provádět volání prvků TooltipService show() a hide() .

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 souboru 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;
            }
        ...
        ...
        }
  • selection: d3.Selection<Element> : Prvky d3, jejichž prostřednictvím se ovládají popisy

  • getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[] : Delegát pro dosazování obsahu popisu (co se má zobrazit) podle kontextu

  • getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: Delegát pro načtení ID datového bodu (v této ukázce se nepoužívá)

  • 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ánek sestavy (možnost upravovat popisy v podokně formátu stránky sestavy), přidejte objekt do tooltips souboru capabilities.json.

Příklad:

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

Popisy pak můžete definovat v podokně Formátování na stránce sestavy.

  • supportedTypes: Konfigurace popisu podporovaná vizuálem a promítla se také 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.

Popis na stránce sestavy

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í do popisů akce přechodu k podrobnostem datového bodu a aktualizují styl tak, aby odpovídal motivu sestavy.

moderní popis

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

Příklad:

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

V kódu SampleBarChart můžete vidět příklad moderní funkce popisů tlačítek.

Poznámka

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

Další kroky