Elemleírások hozzáadása a Power BI-vizualizációkhoz
Az elemleírások elegáns módot kínálnak arra, hogy környezetfüggőbb információkat és részleteket nyújtsanak a vizualizáció adatpontjainak. A Power BI elemleírások API a következő interakciókat képes kezelni:
- Elemleírás megjelenítése.
- Elemleírás elrejtése.
- Elemleírás á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.
A modern elemleírások funkció engedélyezésével módosíthatja az elemleírások stílusát, vagy részletezési műveleteket adhat hozzá.
Az alábbi képen egy elemleírás látható egy mintasávdiagramon:
A fenti elemleírás egy sávkategóriát és értéket mutat be. Az elemleírást kiterjesztheti több érték megjelenítésére.
Elemleírások kezelése
A vizualizáció elemleírásait a ITooltipService felületen keresztül kezelheti. ITooltipService értesíti a gazdagépet, hogy egy elemleírást 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 vizualizációnak észlelnie kell az egéreseményeket a vizualizációban, és szükség szerint meg kell hívnia a show(), move()és hide() meghatalmazottakat az elemleírás-objektumokban options kitöltött megfelelő tartalommal.
TooltipShowOptions és TooltipHideOptions megadhatja, hogy mit jelenítsen meg és hogyan viselkedjen ezekben az eseményekben.
Ezeknek a metódusoknak a meghívása olyan felhasználói eseményeket is magában foglal, mint az egér mozgatása és az események érintése, ezért érdemes figyelőket létrehozni ezekhez az eseményekhez, 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 TooltipServiceaz, hogy a D3 egéreseményeket a megfelelő elemeken figyeli, majd szükség esetén meghívja show() és hide() szükség esetén az elemeket is meghívja.
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 fájlban tekintheti meg.
TooltipServiceWrapper létrehozása
A sávdiagram-konstruktornak most már van egy TooltipServiceWrapper tagja, amelyet a rendszer a konstruktorban a gazdagéppéldánysal tooltipService hoz létre.
private tooltipServiceWrapper: ITooltipServiceWrapper;
this.tooltipServiceWrapper = createTooltipServiceWrapper(this.host.tooltipService, options.element);
Az TooltipServiceWrapper osztály a példányt tooltipService a vizualizáció és az érintési paraméterek D3 gyökérelemeként is tartalmazza.
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. Kijelölési<elem>: Azok a d3 elemek, amelyeken az elemleírások 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? logikai: Logikai érték, amely azt jelzi, hogy frissíteni kell-e az elemleírás adatait egy MouseMove-esemény során (ebben a mintában nem használt).
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.
Elemleírás megjelenítéséhez hívja meg a megjelenítési módszert
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 környezetet a D3 kijelölt elemeiből egy tooltipEventArgs elemleírásba. A koordinátákat is kiszámítja.
- getTooltipInfoDelegate: Ezután létrehozza az elemleírás tartalmát az tooltipEventArgs elemleírásból. Ez a BarChart osztály visszahívása, mert ez a vizualizáció logikája. Ez az elemleírásban megjelenítendő tényleges szöveges tartalom.
- getDataPointIdentity: Ebben a mintában nem használt.
- this.visualHostTooltipService.show: Az elemleírás megjelenítésére szolgáló hívás.
További kezelési lehetőségek találhatók a mintában az eseményekhez és mousemove az eseményekhezmouseout.
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 feltölthet VisualTooltipDataItem[] , amely több sort ad hozzá 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 adatok változhatnak. Ez a hívás a BarChart.update() metódusban történik. Hívás történik az összes "sáv" elem kiválasztásának figyelésére, amely csak a BarChart.getTooltipData()korábban említett elemeket adja át.
this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
(tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
(tooltipEvent: TooltipEventArgs<number>) => null);
Elemleírások támogatása a jelentésoldalon
Jelentésoldali elemleírások támogatásának hozzáadásához (az elemleírások módosításának lehetősége a jelentésoldal formátumpanelén) adjon hozzá egy tooltipsobjektumot a capabilities.json fájlhoz.
Például:
{
"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: A vizualizáció által támogatott és a mezőkben is tükröződő elemleírás-konfiguráció.default: Megadja, hogy az adatmezőn keresztüli "automatikus" elemleírás-kötés támogatott-e.canvas: Megadja, hogy a jelentésoldal elemleírásai 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.
További információ: Jelentésoldali elemleírások használati útmutatója.
A jelentésoldal elemleírásának megjelenítéséhez a Power BI-gazdagép hívásai ITooltipService.Show(options: TooltipShowOptions) után vagy ITooltipService.Move(options: TooltipMoveOptions)a selectionId (identities az előző options argumentum tulajdonsága) értéket használja. Az elemleírás által lekérendő SelectionId értéknek az elem kijelölt adatait (kategória, adatsor stb.) kell jelölnie.
A selectionId elemleírás-megjelenítési hívásokra való küldésére az alábbi kódban látható példa:
this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
(tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
(tooltipEvent: TooltipEventArgs<number>) => tooltipEvent.data.selectionID);
Modern elemleírások támogatása a jelentésoldalon
Az API 3.8.3-s verziójából 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 apiVersion pbiviz.json fájlban.
A jelentésoldal modern elemleírásainak kezeléséhez adja hozzá a supportEnhancedTooltips tulajdonságot aztooltips objektumhoz a capabilities.json fájlban.
Például:
{
"tooltips": {
... ,
"supportEnhancedTooltips": true
}
}
Tekintse meg a SampleBarChart-kódban használt modern elemleírás-funkciót.
Megjegyzé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. Ne feledje, hogy a felhasználónak továbbra is engedélyeznie kell a modern elemleírás funkciót a jelentésbeállításokban.