Pridanie popisov do vizuálov služby Power BI

  • Článok

Popisy sú elegantný spôsob, ako poskytnúť viac kontextových informácií a podrobností o údajových bodoch vo vizuáli. Rozhranie API popisov služby Power BI dokáže pracovať s nasledujúcimi interakciami:

  • Zobrazenie popisu
  • Skryť popis.
  • Premiestnenie popisu

Popisy môžu na konkrétnych súradniciach zobrazovať textové prvky s nadpisom, hodnoty v určitej farbe a priehľadnosť s určitou množinou súradníc. Tieto údaje sa poskytnú rozhraniu API a hostiteľ Power BI ich vykreslí rovnakým spôsobom, akým sa vykresľujú popisy natívnych vizuálov.

Štýl popisov môžete zmeniť alebo môžete pridať akcie prechodu na detaily zapnutím funkcie moderných popisov .

Nasledujúci obrázok znázorňuje popis v ukážkovom pruhovom grafe:

Screenshot that shows sample bar chart tooltips.

Vyššie uvedený obrázok popisu zobrazuje kategóriu a hodnotu jedného pruhu. Popis môžete rozšíriť tak, aby zobrazoval viaceré hodnoty.

Spravovanie popisov

Popisy vo vizuáli môžete spravovať prostredníctvom ITooltipService rozhrania . ITooltipService informuje hostiteľa, že popis sa musí zobraziť, odstrániť alebo premiestniť.

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

Váš vizuál by mal podľa potreby rozpoznať udalosti myši v rámci vizuálu a podľa potreby zavolať show()delegátov , move()a hide() s príslušným obsahom, ktorý sa vyplní do objektov popisu options . TooltipShowOptions a TooltipHideOptions následne definujte, čo sa má zobraziť a tiež to, ako sa správať pri týchto udalostiach.

Volanie týchto metód zahŕňa udalosti používateľa, ako napríklad pohyby myšou a pokyny dotykom, preto je vhodné pre tieto udalosti vytvoriť prijímače, ktoré budú následne vyvolávať TooltipService členy . Nasledujúci príklad sa agreguje v triede nazývanej TooltipServiceWrapper.

Trieda TooltipServiceWrapper

Základným cieľom tejto triedy je uchovávať inštanciu , poslúchať TooltipServiceudalosti myši D3 v prípade relevantných prvkov a potom podľa potreby vykonať volania show() prvkov a hide() .

Táto trieda uchováva a spravuje všetky relevantné stavy a logiku pre tieto udalosti, a to hlavne so prevodom na rozhranie so základným kódom D3. Rozhranie D3 a konverzia nie sú súčasťou obsahu tohto článku.

Vzorový kód v tomto článku je založený na vizuáli SampleBarChart. Zdrojový kód môžete preskúmať v súprave barChart.ts.

Create TooltipServiceWrapper

Konštruktor pruhového grafu TooltipServiceWrapper teraz obsahuje člena , ktorého inštancia sa vytvorí v konštruktore s hostiteľskou tooltipService inštanciou.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

Trieda TooltipServiceWrapper uchováva inštanciu tooltipService tiež ako koreňový prvok D3 parametrov vizuálu a dotykového ovládania.

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

Jediný vstupný bod tejto triedy, ktorý umožňuje zaregistrovať prijímače udalostí, addTooltip je metóda .

Metóda 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. Prvok> výberu<: Prvky D3, prostredníctvom ktorých sa spravujú popisy.
  • getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: Delegát na vyplnenie obsahu popisu (čo sa má zobraziť) podľa kontextu.
  • getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: Delegát na načítanie identifikátora údajového bodu (v tejto ukážke sa nepoužíva).
  • reloadTooltipDataOnMouseMove? booleovská hodnota: booleovská hodnota určujúčná, či sa majú údaje popisu počas udalosti mouseMove obnoviť (v tejto ukážke sa nepoužíva).

Ako vidíte, metóda sa ukončí bez akcie, addTooltip ak tooltipService je položka zakázaná alebo nie je k dispozícii žiaden skutočný výber.

Volanie metódy show na zobrazenie popisu

Metóda addTooltip ďalej počúva udalosť D3 mouseover , ako je znázornené v nasledujúcom kóde:

        ...
        ...
        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 prvkov vybratých z udalosti D3 do tooltipEventArgs. Zároveň vypočíta súradnice.
  • getTooltipInfoDelegate: Následne z tooltipEventArgs vytvorí obsah popisu. Ide o spätné volanie do triedy BarChart, pretože zodpovedá logike vizuálu. Je to skutočný textový obsah, ktorý sa má zobraziť v popise.
  • getDataPointIdentity: V tejto ukážke sa nepoužíva.
  • this.visualHostTooltipService.show: Volanie na zobrazenie popisu.

Ďalšie možnosti spracovania nájdete v ukážke pre mouseout udalosti a mousemove .

Ďalšie informácie nájdete v odkladacom priestore vizuálov SampleBarChart.

Vyplnenie obsahu popisu pomocou metódy getTooltipData

Do triedy BarChart sa pridal getTooltipData člen, ktorý jednoducho extrahuje categoryprvky , valuea color údajové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 predchádzajúcej implementácii header je člen konštantný, ale môžete ho použiť aj v zložitejších implementáciách, ktoré si vyžadujú dynamické hodnoty. Môžete vyplniť VisualTooltipDataItem[] viacerými prvkami, čím sa do popisu pridá viac riadkov. Môže to byť užitočné vo vizuáloch, ako sú napr. skladané pruhové grafy, kde môže popis zobrazovať údaje z viac než jedného údajového bodu.

Volanie metódy addTooltip

Posledným krokom je volanie addTooltip metódy , pokiaľ sa skutočné údaje môžu meniť. Toto volanie sa uskutoční v metóde BarChart.update() . Vykoná sa volanie, ktoré monitoruje výber všetkých "pruhových" prvkov, prechádza iba BarChart.getTooltipData(), ako už bolo uvedené.

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

Pridanie podpory pre popisy na stranu zostavy

Ak chcete pridať podporu popisov strany zostavy (možnosť upraviť popisy na table formátu strany zostavy), pridajte tooltipsobjekt do súboru capabilities.json .

Napríklad:

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

Potom môžete definovať popisy na table Formátovanie na strane zostavy.

  • supportedTypes: Konfigurácia popisov podporovaná vizuálom, ktorá sa odráža v kontajneri polí.
    • default: Určuje, či je podporovaná "automatická" väzba popisov prostredníctvom údajového poľa.
    • canvas: Určuje, či sú podporované popisy strany zostavy.
  • roles: (Voliteľné) Ak je už definovaný, usudzuje, ktoré roly údajov sú viazané na vybratú možnosť popisu v kontajneri polí.

Screenshot that shows the Report page tooltip dialog.

Ďalšie informácie nájdete v pokynoch na používanie popisov strany zostavy.

Ak chcete zobraziť popis strany zostavy, keď hostiteľ služby Power BI zavolá ITooltipService.Show(options: TooltipShowOptions) alebo ITooltipService.Move(options: TooltipMoveOptions), spotrebuje to vlastnosť selectionId (identities vlastnosť predchádzajúceho options argumentu ). Na načítanie popisom by mal prvok SelectionId predstavovať vybraté údaje (kategória, rad atď.) položky, na ktorú ste ukázali myšou.

Príklad odoslania prvku selectionId do volania na zobrazenie popisu je znázornený v nasledujúcom kóde:

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

Pridanie podpory moderných popisov na stranu zostavy

Z rozhrania API verzie 3.8.3 môžete vytvoriť aj moderné vizuálne popisy. Moderné vizuálne popisy pridávaujú akcie prechodu údajových bodov do popisov a aktualizujú štýl tak, aby zodpovedali motívu zostavy. Ak chcete zistiť, ktorú verziu používate, pozrite si apiVersionsúbor pbiviz.json .

Screenshot that shows a modern tooltip.

Ak chcete spravovať podporu moderných popisov stránky zostavy, pridajte supportEnhancedTooltips vlastnosť do tooltipsobjektu v súbore capabilities.json .

Napríklad:

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

Pozrite si príklad funkcie moderných popisov, ktorá sa používa v kóde SampleBarChart .

Poznámka

Pridaním tejto funkcie do súboru capabilities.json môže používateľ povoliť túto funkciu pre zostavu. Nezabúdajte, že používateľ bude musieť v nastaveniach zostavy aj naďalej povoliť funkciu moderného popisu.

Súvisiaci obsah

Pomôcky pre popisy

Prispôsobenie popisov v službe Power BI

Vytváranie popisov na základe strán zostavy v aplikácii Power BI Desktop