Power BI görsellerinize araç ipuçları ekleme
Araç ipuçları , görseldeki veri noktalarına daha bağlamsal bilgiler ve ayrıntılar sağlamanın zarif bir yoludur. Power BI araç ipuçları API'si aşağıdaki etkileşimleri işleyebilir:
- Araç ipucu gösterme.
- Araç ipucu gizleyin.
- Araç ipucu taşıma.
Araç ipuçları, belirli bir koordinat kümesinde başlık, belirli bir renkteki bir değer ve opaklık içeren bir metin öğesi görüntüleyebilir. Bu veriler API'ye sağlanır ve Power BI konağı, yerel görseller için araç ipuçlarını işlediğinden aynı şekilde işler.
Modern araç ipuçları özelliğini etkinleştirerek araç ipuçlarınızın stilini değiştirebilir veya detaya gitme eylemleri ekleyebilirsiniz.
Aşağıdaki görüntüde örnek çubuk grafikteki bir araç ipucu gösterilmektedir:
Yukarıdaki araç ipucu resmi tek bir çubuk kategorisini ve değerini gösterir. Araç ipucunun kapsamını genişleterek birden çok değer görüntüleyebilirsiniz.
Araç ipuçlarını yönetme
Arabirim aracılığıyla ITooltipService görselinizdeki araç ipuçlarını yönetebilirsiniz. ITooltipService bir araç ipucunun görüntülenmesi, kaldırılması veya taşınması gerektiğini konağa bildirir.
interface ITooltipService {
enabled(): boolean;
show(options: TooltipShowOptions): void;
move(options: TooltipMoveOptions): void;
hide(options: TooltipHideOptions): void;
}
Görseliniz, görsel içindeki fare olaylarını algılamalı ve araç ipucu options nesnelerinde uygun içerikle gerektiği gibi , move()ve hide() temsilcilerini çağırmalıdırshow().
TooltipShowOptions ve TooltipHideOptions buna karşılık, bu olaylarda ne görüntüleneceğini ve nasıl davranılacağını tanımlayın.
Bu yöntemleri çağırmak fare taşıma ve dokunma olayları gibi kullanıcı olaylarını içerir, bu nedenle bu olaylar için dinleyiciler oluşturmak ve bu da üyeleri çağırmak TooltipService için iyi bir fikirdir.
Aşağıdaki örnek adlı TooltipServiceWrapperbir sınıfta toplanır.
TooltipServiceWrapper sınıfı
Bu sınıfın ardındaki temel fikir, örneğini TooltipServicetutmak, ilgili öğelerin üzerinde D3 fare olaylarını dinlemek ve gerektiğinde ve hide() öğelerine show() çağrı yapmaktır.
sınıfı, çoğunlukla temel alınan D3 koduyla birlikte çalışmak üzere tasarlanmış olan bu olaylar için ilgili durum ve mantığı barındırıp yönetir. D3 birlikte çalışma ve dönüştürme, bu makalenin kapsamı dışındadır.
Bu makaledeki örnek kod, SampleBarChart görselini temel alır. kaynak kodunu barChart.ts dosyasında inceleyebilirsiniz.
TooltipServiceWrapper Oluşturma
Çubuk grafik oluşturucusunun artık konak tooltipService örneğiyle oluşturucuda örneklenen bir TooltipServiceWrapper üyesi vardır.
private tooltipServiceWrapper: ITooltipServiceWrapper;
this.tooltipServiceWrapper = createTooltipServiceWrapper(this.host.tooltipService, options.element);
TooltipServiceWrapper sınıfı, görsel ve dokunma parametrelerinin tooltipService kök D3 öğesi olarak da örneği tutar.
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;
}
.
.
.
}
Bu sınıfın olay dinleyicilerini kaydetmek için tek giriş noktası yöntemidir addTooltip .
addTooltip yöntemi
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;
}
...
...
}
- seçim: d3. Seçim<Öğesi>: Araç ipuçlarının işlendiği d3 öğeleri.
- getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: Bağlam başına araç ipucu içeriğini doldurma temsilcisi (görüntülenecek olanlar).
- getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: Veri noktası kimliğini almak için temsilci (bu örnekte kullanılmadı).
- reloadTooltipDataOnMouseMove? boolean: Bir MouseMove olayı sırasında araç ipucu verilerinin yenilenip yenilenmeyeceğini belirten boole değeri (bu örnekte kullanılmadı).
Gördüğünüz gibi, addTooltip devre dışı bırakılmışsa tooltipService veya gerçek bir seçim yoksa eylem olmadan çıkılır.
Araç ipucu görüntülemek için show yöntemini çağırma
addTooltip yöntemi aşağıdaki kodda gösterildiği gibi D3 mouseover olayını dinler:
...
...
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: Seçilen D3 öğelerinden bağlamı bir araç ipucuEventArgs içine ayıklar. Koordinatları da hesaplar.
- getTooltipInfoDelegate: Daha sonra tooltipEventArgs araç ipucu içeriğini oluşturur. Bu, görselin mantığı olduğundan BarChart sınıfına yapılan bir geri çağırmadır. Araç ipucunda görüntülenecek gerçek metin içeriğidir.
- getDataPointIdentity: Bu örnekte kullanılmadı.
- this.visualHostTooltipService.show: Araç ipucunun görüntüleneceği çağrı.
ve mousemove olayları için mouseout örnekte ek işleme bulunabilir.
Daha fazla bilgi için bkz . SampleBarChart görsel deposu.
getTooltipData yöntemiyle araç ipucu içeriğini doldurun
BarChart sınıfı, getTooltipData veri noktasının category, valueve color değerlerini VisualTooltipDataItem[] öğesine ayıklayan bir üyeyle eklendi.
private static getTooltipData(value: any): VisualTooltipDataItem[] {
return [{
displayName: value.category,
value: value.value.toString(),
color: value.color,
header: 'ToolTip Title'
}];
}
Önceki uygulamada, header üye sabittir, ancak dinamik değerler gerektiren daha karmaşık uygulamalar için bunu kullanabilirsiniz. öğesini, araç ipucuna VisualTooltipDataItem[] birden çok satır ekleyen birden çok öğeyle doldurabilirsiniz. Araç ipucunun tek bir veri noktasından daha fazla veri görüntüleyebileceği yığılmış çubuk grafikler gibi görsellerde yararlı olabilir.
addTooltip yöntemini çağırma
Son adım, gerçek veriler değişebileceğinden yöntemini çağırmaktır addTooltip . Bu çağrı yönteminde BarChart.update() gerçekleşir. Daha önce belirtildiği gibi yalnızca öğesini geçirerek tüm "çubuk" öğelerinin BarChart.getTooltipData()seçimini izlemek için bir çağrı yapılır.
this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
(tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
(tooltipEvent: TooltipEventArgs<number>) => null);
Rapor sayfasına araç ipuçları desteği ekleme
Rapor sayfası araç ipuçları desteği (rapor sayfasının biçim bölmesinde araç ipuçlarını değiştirme özelliği) eklemek için capabilities.json dosyasına birtooltips nesne ekleyin.
Örneğin:
{
"tooltips": {
"supportedTypes": {
"default": true,
"canvas": true
},
"roles": [
"tooltips"
]
}
}
Ardından, araç ipuçlarını rapor sayfasının Biçimlendirme bölmesinden tanımlayabilirsiniz.
supportedTypes: Görsel tarafından desteklenen ve alanlara yansıtılan araç ipucu yapılandırması.default: Veri alanı aracılığıyla "otomatik" araç ipuçları bağlamasının desteklenip desteklenmediğini belirtir.canvas: Rapor sayfası araç ipuçlarının desteklenip desteklenmediğini belirtir.
roles: (İsteğe bağlı) Tanımlandıktan sonra, alanlar kutusunda hangi veri rollerinin seçili araç ipucu seçeneğine bağlı olduğunu açıklar.
Daha fazla bilgi için bkz . Rapor sayfası araç ipuçları kullanım yönergeleri.
Rapor sayfası araç ipucunun görüntülenmesi için, Power BI ana bilgisayarı veya çağrısından ITooltipService.Show(options: TooltipShowOptions) sonra selectionId değerini (identities önceki options bağımsız değişkenin özelliği) ITooltipService.Move(options: TooltipMoveOptions)kullanır. Araç ipucu tarafından alınması için SelectionId, üzerine geldiğiniz öğenin seçili verilerini (kategori, seri vb.) temsil etmelidir.
SelectionId değerini araç ipucu görüntüleme çağrılarına gönderme örneği aşağıdaki kodda gösterilmiştir:
this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
(tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
(tooltipEvent: TooltipEventArgs<number>) => tooltipEvent.data.selectionID);
Rapor sayfasına modern araç ipuçları desteği ekleme
API sürüm 3.8.3'ten modern görsel araç ipuçları da oluşturabilirsiniz. Modern görsel araç ipuçları, araç ipuçlarınıza veri noktası detaylandırma eylemleri ekler ve stili rapor temanızla eşleşecek şekilde güncelleştirir. Hangi sürümü kullandığınızı öğrenmek için pbiviz.json dosyasını denetleyin apiVersion .
Rapor sayfası modern araç ipuçları desteğini yönetmek için capabilities.json dosyasındaki nesnesine tooltips özelliğini ekleyinsupportEnhancedTooltips.
Örneğin:
{
"tooltips": {
... ,
"supportEnhancedTooltips": true
}
}
SampleBarChart kodunda kullanılan modern araç ipuçları özelliğinin bir örneğine bakın.
Dekont
Bu özelliği capabilities.json dosyasına eklemek, kullanıcıya bu özelliği rapor için etkinleştirme olanağı sağlar. Kullanıcının rapor ayarlarında modern araç ipucu özelliğini etkinleştirmesi gerekeceğini unutmayın.