Tooltippek hozzáadása a Power BI-vizualizációkhoz

A tooltipok elegáns módot kínálnak arra, hogy környezetfüggő információkat és részleteket nyújtsanak a vizualizáció adatpontjainak. A Power BI eszköztippek API a következő interakciók kezelésére képes:

  • Elemleírás megjelenítése.
  • Elemleírás elrejtése.
  • Magyarázó szöveg áthelyezése.

Az elemleírások megjeleníthetnek egy szöveges elemet címmel, egy adott színben lévő értéket és egy adott koordinátákon lévő átlátszóságot. Ezeket az adatokat az API biztosítja, és a Power BI-gazdagép ugyanúgy jeleníti meg azokat, mint a natív vizualizációk elemleírásait.

Az eszköztippek stílusát módosíthatja, vagy részletező műveleteket adhat hozzá a modern eszköztippek funkció engedélyezésével.

Az alábbi képen egy eszköztipp látható egy minta sávdiagramon.

Képernyőkép, amely megmutatja a mintasávdiagram segédleteit.

A fenti tooltip kép egy sáv kategóriát és értéket ábrázolja. Bővítheti a súgóablakot, hogy több értéket jelenítsen meg.

Tooltipok kezelése

A vizualizáció elemleírásait a ITooltipService felületen keresztül kezelheti. ITooltipService értesíti a gazdagépet, hogy egy tooltipet kell megjeleníteni, eltávolítani vagy áthelyezni.

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

A vizuálisnak észlelnie kell az egéreseményeket, és szükség szerint meg kell hívnia a show(), move(), és hide() delegátusokat az elemleírás options objektumaiba kitöltött megfelelő tartalommal. TooltipShowOptions és TooltipHideOptions meghatározzák, hogy mit jelenítsenek meg és hogyan viselkedjenek ezekben az eseményekben.

Az ilyen metódusok meghívása magában foglalja a felhasználói eseményeket, például az egér mozgatását és az érintési eseményeket, ezért érdemes figyelőket létrehozni ezekre az eseményekre, amelyek viszont meghívják a TooltipService tagokat. Az alábbi példa aggregátumokat ad egy úgynevezett TooltipServiceWrapperosztályban.

Az TooltipServiceWrapper osztály

Az osztály alapgondolata az, hogy megőrizze a TooltipService példányt, a D3 egéreseményeket a megfelelő elemeken figyelje, majd szükség esetén hívja a show() és hide() elemeket.

Az osztály minden releváns állapotot és logikát tárol és kezel ezekhez az eseményekhez, amelyek többnyire az alapul szolgáló D3-kóddal való együttműködésre irányulnak. A D3-beli együttműködés és átalakítás nem terjed ki a jelen cikkre.

A cikkben szereplő példakód a SampleBarChart vizualizáción alapul. A forráskódot a barChart.ts tekintheti meg.

TooltipServiceWrapper létrehozása

A oszlopdiagram-konstruktornak most már van egy TooltipServiceWrapper tagja, amelyet a konstruktorban példányosítanak a gazdagép tooltipService példányával.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

Az TooltipServiceWrapper osztály tartalmazza a tooltipService példányt, mint a vizualizáció és az érintési paraméterek D3 gyökérelemét is.

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

Az osztály egyetlen belépési pontja az eseményfigyelők regisztrálásához a addTooltip metódus.

Az addTooltip metódus

        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;
            }
        ...
        ...
        }
  • kijelölés: d3.Selection<Elem>: Azok a d3 elemek, amelyeken a tooltippek kezelhetők.
  • getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: Az elemleírás-tartalom (mit kell megjeleníteni) környezetenkénti feltöltésére szolgáló delegált.
  • getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: Az adatpont azonosítójának lekérésére szolgáló delegált (ebben a mintában nem használt).
  • reloadTooltipDataOnMouseMove? booleán: Egy logikai érték, amely azt jelzi, hogy frissíteni kell-e az elemleírás adatait egy MouseMove esemény során (nem használt ebben a mintában).

Mint látható, addTooltip a művelet nélküli kilépés, ha a tooltipService le van tiltva, vagy nincs valódi kijelölés.

Az elemleírás megjelenítéséhez hívja meg a show metódust.

A addTooltip metódus ezután figyeli a D3 mouseover eseményt, ahogy az a következő kódban is látható:

        ...
        ...
        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: Kinyeri a kontextust a D3 kijelölt elemeiből egy tooltipEventArgs objektumba. A koordinátákat is kiszámítja.
  • getTooltipInfoDelegate: Ezután felépíti az elemleírás tartalmát a tooltipEventArgs alapján. Ez egy visszahívás a BarChart osztályhoz, mivel ez felelős a vizualizáció logikájáért. Ez a tooltipben megjelenítendő tényleges szöveges tartalom.
  • getDataPointIdentity: Ebben a mintában nem használt.
  • this.visualHostTooltipService.show: A tooltip megjelenítési hívása.

További kezelési lehetőségek találhatók a mintában a mouseout és mousemove típusú eseményekhez.

További információ: SampleBarChart vizualizációs adattár.

Töltse ki az elemleírás tartalmát a getTooltipData metódussal

A BarChart osztály egy getTooltipData taggal lett hozzáadva, amely egyszerűen kinyeri a category, valueés color az adatpontot egy VisualTooltipDataItem[] elembe.

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

Az előző implementációban a header tag állandó, de összetettebb implementációkhoz is használhatja, amelyek dinamikus értékeket igényelnek. Egynél több elemet is hozzáadhat a VisualTooltipDataItem[]-hoz, ami több sort ad az elemleíráshoz. Olyan vizualizációkban hasznos lehet, mint a halmozott sávdiagramok, ahol az elemleírás több adatpont adatait is megjelenítheti.

Az addTooltip metódus meghívása

Az utolsó lépés a metódus meghívása addTooltip, amikor a tényleges adat megváltozhat. Ez a hívás a BarChart.update() metódusban történik. Hívást kezdeményeznek az összes "sáv" elem kiválasztásának figyelésére, csak a BarChart.getTooltipData() elemet átadva, ahogyan azt korábban említettük.

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

Adja hozzá az eszköztippeket a jelentésoldalhoz.

A jelentésoldal elemleírásainak támogatásához (az elemleírások módosításának lehetősége a jelentésoldal formátumpanelén) vegyen fel egy tooltipsobjektumot a capabilities.json fájlba.

Példa:

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

Ezután a jelentésoldal Formázás paneljén definiálhatja az elemleírásokat.

  • supportedTypes: Az elemleírás-konfiguráció, amelyet a vizualizáció támogat, jól tükröződik a mezőkben.
    • default: Meghatározza, hogy az adatmezőn keresztüli "automatikus" eszköztipp kötése támogatott-e.
    • canvas: Meghatározza, hogy a jelentésoldali eszköztippek támogatottak-e.
  • roles: (Nem kötelező) A definiálás után azt jelzi, hogy mely adatszerepkörök vannak kötve a mezők kijelölt elemleírás-beállításához.

Képernyőkép a Jelentés lap súgó buborék párbeszédpanelről.

További információ: A jelentésoldal tooltipinek használati útmutatója.

A jelentésoldal elemleírásának megjelenítéséhez, miután a Power BI-gazda hívja a ITooltipService.Show(options: TooltipShowOptions) vagy a ITooltipService.Move(options: TooltipMoveOptions)-t, felhasználja a selectionId-t (az előző identities argumentum options tulajdonsága). Az eszköztipp által visszaadott SelectionId értéknek a kijelölt adatokat (kategória, adatsor stb.) kell jelölnie azon elemhez, amely fölé az egérrel rámutatott.

Példa a selectionId eszköztár-megjelenítési hívásoknak való elküldésére az alábbi kódban látható:

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

Adjunk hozzá modern elemleírások támogatását a jelentésoldalhoz

Az API 3.8.3 verziójától kezdve modern vizuális elemleírásokat is létrehozhat. A modern vizuális elemleírások adatpont-részletezési műveleteket adnak hozzá az elemleírásokhoz, és frissítik a stílust a jelentés témájának megfelelően. Ha meg szeretné tudni, hogy melyik verziót használja, ellenőrizze a apiVersionpbiviz.json fájlban.

Modern súgómegjegyzést megjelenítő képernyőkép.

A jelentésoldal modern eszköztippjeinek kezeléséhez adja hozzá a supportEnhancedTooltips tulajdonságot az tooltipsobjektumhoz a capabilities.json fájlban.

Példa:

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

Tekintse meg a modern elemleírások funkciójának példáját, amelyet a SampleBarChart kódban használnak.

Feljegyzés

Ha hozzáadja ezt a funkciót a capabilities.json fájlhoz, lehetővé teszi a felhasználó számára a funkció engedélyezését a jelentéshez.

Kapcsolódó tartalom

  • Last updated on