Knopinfo toevoegen aan uw Power BI-visuals
Knopinfo is een elegante manier om meer contextuele informatie en details te bieden aan gegevenspunten in een visual. De API voor power BI-knopinfo kan de volgende interacties verwerken:
- Knopinfo weergeven.
- Knopinfo verbergen.
- Knopinfo verplaatsen.
Knopinfo kan een tekstueel element weergeven met een titel, een waarde in een bepaalde kleur en dekking op een opgegeven set coördinaten. Deze gegevens worden aan de API verstrekt en de Power BI-host geeft deze op dezelfde manier weer als knopinfo voor systeemeigen visuals.
U kunt de stijl van uw knopinfo wijzigen of booracties toevoegen door de moderne functie voor knopinfo in te schakelen.
In de volgende afbeelding ziet u knopinfo in een voorbeeld van een staafdiagram:
In de bovenstaande knopinfoafbeelding ziet u een categorie met één staaf en een waarde. U kunt de knopinfo uitbreiden om meerdere waarden weer te geven.
Knopinfo beheren
U kunt de knopinfo in uw visual beheren via de ITooltipService
interface. ITooltipService
hiermee wordt de host op de hoogte gebracht dat knopinfo moet worden weergegeven, verwijderd of verplaatst.
interface ITooltipService {
enabled(): boolean;
show(options: TooltipShowOptions): void;
move(options: TooltipMoveOptions): void;
hide(options: TooltipHideOptions): void;
}
Uw visual moet muisgebeurtenissen in de visual detecteren en de show()
, move()
en hide()
gemachtigden, indien nodig, aanroepen met de juiste inhoud die is ingevuld in de knopinfoobjecten options
.
TooltipShowOptions
en TooltipHideOptions
definieer op zijn beurt wat u wilt weergeven en hoe u zich moet gedragen in deze gebeurtenissen.
Het aanroepen van deze methoden omvat gebruikersevenementen zoals muisbewegingen en aanraakevenementen, dus het is een goed idee om listeners te maken voor deze gebeurtenissen, waardoor de TooltipService
leden op hun beurt worden aangeroepen.
Het volgende voorbeeld wordt samengevoegd in een klasse met de naam TooltipServiceWrapper
.
De klasse TooltipServiceWrapper
Het basisidee achter deze klasse is het houden van het exemplaar van de TooltipService
, luisteren naar D3-muisgebeurtenissen over relevante elementen en vervolgens de aanroepen naar show()
en hide()
de elementen wanneer dat nodig is.
De klasse bevat en beheert alle relevante status en logica voor deze gebeurtenissen, die voornamelijk zijn gericht op communicatie met de onderliggende D3-code. De D3-communicatie en -conversie valt buiten het bereik van dit artikel.
De voorbeeldcode in dit artikel is gebaseerd op de visual SampleBarChart. U kunt de broncode in barChart.ts onderzoeken.
TooltipServiceWrapper maken
De staafdiagramconstructor heeft nu een TooltipServiceWrapper
lid dat wordt geïnstantieerd in de constructor met het hostexemplaren tooltipService
.
private tooltipServiceWrapper: ITooltipServiceWrapper;
this.tooltipServiceWrapper = createTooltipServiceWrapper(this.host.tooltipService, options.element);
De TooltipServiceWrapper
klasse bevat het tooltipService
exemplaar, ook als het hoofdelement D3 van de visual en aanraakparameters.
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;
}
.
.
.
}
Het enige toegangspunt voor deze klasse voor het registreren van gebeurtenislisteners is de addTooltip
methode.
De methode 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;
}
...
...
}
- selectie: d3. Selectie-element<>: De d3-elementen over welke knopinfo wordt verwerkt.
- getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: De gemachtigde voor het vullen van de inhoud van knopinfo (wat moet worden weergegeven) per context.
- getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: de gemachtigde voor het ophalen van de gegevenspunt-id (ongebruikt in dit voorbeeld).
- reloadTooltipDataOnMouseMove? Booleaanse waarde: Een Booleaanse waarde die aangeeft of de knopinfogegevens moeten worden vernieuwd tijdens een MouseMove-gebeurtenis (ongebruikt in dit voorbeeld).
Zoals u kunt zien, addTooltip
wordt afgesloten zonder actie als de tooltipService
optie is uitgeschakeld of als er geen echte selectie is.
De weergavemethode aanroepen om knopinfo weer te geven
De addTooltip
methode luistert vervolgens naar de D3-gebeurtenis mouseover
, zoals wordt weergegeven in de volgende 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: Extraheert de context van de geselecteerde D3-elementen in een tooltipEventArgs. De coördinaten worden ook berekend.
- getTooltipInfoDelegate: vervolgens wordt de inhoud van de knopinfo opgebouwd uit de tooltipEventArgs. Het is een callback naar de BarChart-klasse, omdat het de logica van de visual is. Het is de werkelijke tekstinhoud die moet worden weergegeven in de knopinfo.
- getDataPointIdentity: Ongebruikt in dit voorbeeld.
- this.visualHostTooltipService.show: De aanroep om de knopinfo weer te geven.
Aanvullende verwerking vindt u in het voorbeeld voor mouseout
en mousemove
gebeurtenissen.
Zie de visualopslagplaats SampleBarChart voor meer informatie.
De inhoud van de knopinfo vullen met de methode getTooltipData
De BarChart-klasse is toegevoegd met een getTooltipData
lid, waarmee het gegevenspunt value
color
eenvoudigweg wordt geëxtraheerd category
naar een VisualTooltipDataItem[]-element.
private static getTooltipData(value: any): VisualTooltipDataItem[] {
return [{
displayName: value.category,
value: value.value.toString(),
color: value.color,
header: 'ToolTip Title'
}];
}
In de voorgaande implementatie is het header
lid constant, maar u kunt het gebruiken voor complexere implementaties, waarvoor dynamische waarden zijn vereist. U kunt het VisualTooltipDataItem[]
met meer dan één element vullen, waardoor meerdere regels aan de knopinfo worden toegevoegd. Het kan handig zijn in visuals, zoals gestapelde staafdiagrammen, waarbij de knopinfo mogelijk gegevens van meer dan één gegevenspunt weergeeft.
De methode addTooltip aanroepen
De laatste stap is het aanroepen van de addTooltip
methode wanneer de werkelijke gegevens kunnen veranderen. Deze aanroep vindt plaats in de BarChart.update()
methode. Er wordt een aanroep gedaan om de selectie van alle 'staaf'-elementen te controleren, waarbij alleen de BarChart.getTooltipData()
, zoals eerder vermeld, wordt doorgegeven.
this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
(tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
(tooltipEvent: TooltipEventArgs<number>) => null);
Ondersteuning voor knopinfo toevoegen aan de rapportpagina
Als u knopinfo voor rapportpagina's wilt toevoegen (de mogelijkheid om knopinfo te wijzigen in het opmaakvenster van de rapportpagina), voegt u een tooltips
object toe aan het capabilities.json-bestand .
Voorbeeld:
{
"tooltips": {
"supportedTypes": {
"default": true,
"canvas": true
},
"roles": [
"tooltips"
]
}
}
Vervolgens kunt u de knopinfo definiëren vanuit het opmaakvenster van de rapportpagina.
supportedTypes
: De configuratie van knopinfo die wordt ondersteund door de visual en wordt weergegeven in de velden.default
: Hiermee geeft u op of de 'automatische' knopinfobinding via het gegevensveld wordt ondersteund.canvas
: Hiermee geeft u op of de knopinfo voor de rapportpagina wordt ondersteund.
roles
: (Optioneel) Nadat deze is gedefinieerd, geeft deze aan welke gegevensrollen zijn gebonden aan de geselecteerde knopinfooptie in de velden.
Zie de gebruiksrichtlijnen voor knopinfo voor rapportpagina's voor meer informatie.
Als u de knopinfo voor de rapportpagina wilt weergeven nadat de Power BI-host wordt aanroepen ITooltipService.Show(options: TooltipShowOptions)
of ITooltipService.Move(options: TooltipMoveOptions)
, wordt de selectionId (identities
eigenschap van het voorgaande options
argument) gebruikt. Als u wilt worden opgehaald met de knopinfo, moet SelectionId de geselecteerde gegevens (categorie, reeks, enzovoort) van het item vertegenwoordigen dat u aanwijst.
Een voorbeeld van het verzenden van de selectionId naar weergaveaanroepen voor knopinfo wordt weergegeven in de volgende code:
this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
(tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
(tooltipEvent: TooltipEventArgs<number>) => tooltipEvent.data.selectionID);
Ondersteuning voor moderne knopinfo toevoegen aan de rapportpagina
Vanuit API-versie 3.8.3 kunt u ook moderne visuele knopinfo maken. Moderne visuele knopinfo voegt drillacties voor gegevenspunten toe aan uw knopinfo en werk de stijl bij zodat deze overeenkomt met het rapportthema. Als u wilt achterhalen welke versie u gebruikt, controleert u het apiVersion
bestand in het pbiviz.json .
Als u de ondersteuning voor moderne knopinfo voor rapportpagina's wilt beheren, voegt u de supportEnhancedTooltips
eigenschap toe aan het tooltips
object in het capabilities.json-bestand .
Voorbeeld:
{
"tooltips": {
... ,
"supportEnhancedTooltips": true
}
}
Bekijk een voorbeeld van de moderne knopinfofunctie die wordt gebruikt in de SampleBarChart-code .
Notitie
Als u deze functie toevoegt aan het capabilities.json-bestand , heeft de gebruiker de mogelijkheid om deze functie voor het rapport in te schakelen. Houd er rekening mee dat de gebruiker nog steeds de moderne knopinfofunctie moet inschakelen in de rapportinstellingen.