Popisy ve vizuálech Power BITooltips in Power BI visuals

Vizuály nyní mohou využívat podporu popisů v Power BI.Visuals can now make use of Power BI tooltip support. Popisy v Power BI nabízejí následující interakce:Power BI tooltips handle the following interactions:

  • Zobrazení popisuShow a tooltip.
  • Skrytí popisuHide a tooltip.
  • Přesunutí popisuMove a tooltip.

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í.Tooltips can display a textual element with a title, a value in a given color, and opacity at a specified set of coordinates. 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ů.This data is provided to the API, and the Power BI host renders it the same way it renders tooltips for native visuals.

Na následujícím obrázku je zobrazený popis v ukázkovém pruhovém grafu:A tooltip in a sample bar chart is shown in the following image:

Popisy v ukázkovém pruhovém grafu

Předchozí obrázek popisu znázorňuje kategorii a hodnotu pro jeden pruh.The preceding tooltip image illustrates a single bar category and value. Jeden popis lze rozšířit tak, aby zobrazoval několik hodnot.You can extend a single tooltip to display multiple values.

Správa popisůManage tooltips

Popisy se spravují prostřednictvím rozhraní ITooltipService.The interface through which you manage tooltips is the "ITooltipService." Informuje hostitele o tom, že je potřeba zobrazit, odebrat nebo přesunout popis.It's used to notify the host that a tooltip needs to be displayed, removed, or moved.

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

Vizuál musí naslouchat událostem myši, ke kterým u něho dojde, a podle potřeby volat delegáty show(), move() a hide() s odpovídajícím obsahem, který se dosadí do objektů Tooltip****Options.Your visual needs to listen to the mouse events within your visual and call the show(), move(), and hide() delegates, as needed, with the appropriate content populated in the Tooltip****Options objects. Objekty TooltipShowOptions a TooltipHideOptions pak definují, co se má zobrazit, a jak se při těchto událostech chovat.TooltipShowOptions and TooltipHideOptions would in turn define what to display and how to behave in these events.

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.Because calling these methods involves user events such as mouse moves and touch events, it's a good idea to create listeners for these events, which would in turn invoke the TooltipService members. Naše ukázka se agreguje ve třídě s názvem TooltipServiceWrapper.Our sample aggregates in a class called TooltipServiceWrapper.

Třída TooltipServiceWrapperThe TooltipServiceWrapper class

Základním účelem této třídy je uchovávat instanci TooltipService, naslouchat událostem myši D3 u relevantních prvků a potom v případě potřeby provádět volání prvků show() a hide().The basic idea behind this class is to hold the instance of the TooltipService, listen to D3 mouse events over relevant elements, and then make the calls to show() and hide() the elements when needed.

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.The class holds and manages any relevant state and logic for these events, which are mostly geared at interfacing with the underlying D3 code. Komunikací přes rozhraní D3 a souvisejícími převody se tento článek nezabývá.The D3 interfacing and conversion is out of scope for this article.

Úplný vzorový kód najdete v úložišti vizuálu SampleBarChart.You can find the full sample code in SampleBarChart visual repository.

Vytvoření třídy TooltipServiceWrapperCreate TooltipServiceWrapper

Konstruktor pruhového grafu teď obsahuje člen TooltipServiceWrapper, jehož instance se vytvoří v konstruktoru s hostitelskou instancí tooltipService.The bar chart constructor now has a TooltipServiceWrapper member, which is instantiated in the constructor with the host tooltipService instance.

        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í.The TooltipServiceWrapper class holds the tooltipService instance, also as the root D3 element of the visual and touch parameters.

    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.The single entry point for this class to register event listeners is the addTooltip method.

Metoda addTooltipThe addTooltip method

        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 : Prvky d3, jejichž prostřednictvím se ovládají popisyselection: d3.Selection: The d3 elements over which tooltips are handled.

  • getTooltipInfoDelegate: (args: TooltipEventArgs) => VisualTooltipDataItem[] : Delegát pro dosazování obsahu popisu (co se má zobrazit) podle kontextugetTooltipInfoDelegate: (args: TooltipEventArgs) => VisualTooltipDataItem[]: The delegate for populating the tooltip content (what to display) per context.

  • getDataPointIdentity: (args: TooltipEventArgs) => ISelectionId: Delegát pro načtení ID datového bodu (v této ukázce se nepoužívá)getDataPointIdentity: (args: TooltipEventArgs) => ISelectionId: The delegate for retrieving the data point ID (unused in this sample).

  • 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á)reloadTooltipDataOnMouseMove? boolean: A Boolean that indicates whether to refresh the tooltip data during a MouseMove event (unused in this sample).

Jak vidíte, addTooltip se ukončuje bez akce, pokud je položka tooltipService zakázaná nebo neexistuje žádný skutečný výběr.As you can see, addTooltip exits with no action if the tooltipService is disabled or there's no real selection.

Volání metody show pro zobrazení popisuCall the show method to display a tooltip

Metoda addTooltip dále naslouchá události D3 mouseover, jak ukazuje následující kód:The addTooltip method next listens to the D3 mouseover event, as shown in the following code:

        ...
        ...
        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.makeTooltipEventArgs: Extracts the context from the D3 selected elements into a tooltipEventArgs. Zároveň vypočítá souřadnice.It calculates the coordinates as well.

  • getTooltipInfoDelegate: Pak z tooltipEventArgs sestaví obsah popisu.getTooltipInfoDelegate: It then builds the tooltip content from the tooltipEventArgs. Jedná se o zpětné volání do třídy BarChart, protože jde o logiku vizuálu.It's a callback to the BarChart class, because it is the visual's logic. To je skutečný textový obsah, který se má v popisu zobrazit.It's the actual text content to display in the tooltip.

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

  • this.visualHostTooltipService.show: Volání pro zobrazení popisuthis.visualHostTooltipService.show: The call to display the tooltip.

Další akce najdete v ukázce pro události mouseout a mousemove.Additional handling can be found in the sample for mouseout and mousemove events.

Další informace najdete v úložišti vizuálů pro SampleBarChart.For more information, see the SampleBarChart visual repository.

Dosazení obsahu popisu metodou getTooltipDataPopulate the tooltip content by the getTooltipData method

Třída BarChart byla přidána s členem getTooltipData, který jednoduše extrahuje category, value a color datového bodu do prvku VisualTooltipDataItem[].The BarChart class was added with a getTooltipData member, which simply extracts the category, value, and color of the data point into a VisualTooltipDataItem[] element.

        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.In the preceding implementation, the header member is constant, but you can use it for more complex implementations, which require dynamic values. Do VisualTooltipDataItem[] můžete dosadit více než jeden prvek, čímž do popisu přidáte více řádků.You can populate the VisualTooltipDataItem[] with more than one element, which adds multiple lines to the tooltip. 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.It can be useful in visuals such as stacked bar charts where the tooltip may display data from more than a single data point.

Volání metody addTooltipCall the addTooltip method

Posledním krokem je volání metody addTooltip, pokud se skutečná data mohou měnit.The final step is to call the addTooltip method when the actual data might change. Toto volání probíhá v metodě BarChart.update().This call takes place in the BarChart.update() method. 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.A call is made to monitor the selection of all the 'bar' elements, passing only the BarChart.getTooltipData(), as mentioned previously.

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

Přidání popisů stránky sestavyAdd report page tooltips

Pokud chcete přidat podporu pro popisy stránek sestavy, najdete většinu změn v souboru capabilities.json.To add report page tooltips support, you'll find most changes in the capabilities.json file.

Vzorové schéma:A sample schema is

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

Popisy stránek sestavy můžete definovat v podokně Formát.You can define report page tooltips in the Format pane.

Popis na stránce sestavy

  • supportedTypes: Konfigurace popisu, která je podporována vizuálem a promítnuta také do polí.supportedTypes: The tooltip configuration that's supported by the visual and reflected in the fields well.

    • default: Určuje, jestli se podporuje „automatická“ vazba popisů přes datové pole.default: Specifies whether the "automatic" tooltips binding via the data field is supported.
    • canvas: Určuje, jestli se podporují popisy stránek sestavy.canvas: Specifies whether the report page tooltips are supported.
  • roles: (Nepovinné) Po definování udává, jaké role dat jsou vázané k vybrané možnosti popisu také v polích.roles: (Optional) After it's defined, it instructs what data roles are bound to the selected tooltip option in the fields well.

Další informace najdete v pokynech k použití popisů stránek sestavy.For more information, see Report page tooltips usage guidelines.

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).To display the report page tooltip, after the Power BI host calls ITooltipService.Show(options: TooltipShowOptions) or ITooltipService.Move(options: TooltipMoveOptions), it consumes the selectionId (identities property of the preceding options argument). 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ší.To be retrieved by the tooltip, SelectionId should represent the selected data (category, series, and so on) of the item you hovered over.

Příklad odeslání prvku selectionId do volání pro zobrazení popisu je uvedený v následujícím kódu:An example of sending the selectionId to tooltip display calls is shown in the following code:

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