Добавление подсказок в визуальные элементы Power BI
Подсказки — это элегантный способ предоставления более контекстной информации и подробных сведений точкам данных на визуальном элементе. API подсказок Power BI может обрабатывать следующие взаимодействия:
- Отображение подсказки.
- Скрытие подсказки.
- Перемещение подсказки.
Подсказки могут отображать текстовый элемент с заголовком, значением заданного цвета и непрозрачностью в указанном наборе координат. Эти данные предоставляются API, а узел Power BI отрисовывает его так же, как и подсказки для собственных визуальных элементов.
Вы можете изменить стиль подсказок или добавить действия бурения, включив современные подсказки .
На следующем рисунке показана подсказка в примере линейчатой диаграммы:
На приведенном выше рисунке подсказки показана одна линейчатая категория и значение. Вы можете расширить подсказку для отображения нескольких значений.
Управление подсказками
Подсказки в визуальном элементе ITooltipService можно управлять с помощью интерфейса. ITooltipService Уведомляет узел о том, что подсказка должна отображаться, удалена или перемещена.
interface ITooltipService {
enabled(): boolean;
show(options: TooltipShowOptions): void;
move(options: TooltipMoveOptions): void;
hide(options: TooltipHideOptions): void;
}
Визуальный элемент должен обнаруживать события мыши в визуальном элементе и вызывать show()move(), а hide() также делегаты, при необходимости, с соответствующим содержимым, заполненным в объектах подсказкиoptions.
TooltipShowOptions и TooltipHideOptions , в свою очередь, определите, что отображать и как вести себя в этих событиях.
Вызов этих методов включает в себя события пользователя, такие как перемещение мыши и сенсорные события, поэтому рекомендуется создавать прослушиватели для этих событий, что, в свою очередь, вызовет TooltipService элементы.
В следующем примере агрегаты в классе с именем TooltipServiceWrapper.
Класс TooltipServiceWrapper
Основная идея этого класса заключается в том, чтобы хранить экземпляр события TooltipServiceмыши D3, прослушивать события мыши D3 над соответствующими элементами, а затем выполнять вызовы show() и hide() элементы при необходимости.
Класс содержит и управляет любым соответствующим состоянием и логикой для этих событий, которые в основном ориентированы на взаимодействие с базовым кодом D3. Взаимодействие d3 и преобразование не область для этой статьи.
Пример кода в этой статье основан на визуальном элементе SampleBarChart. Исходный код можно проверить в barChart.ts.
Создание tooltipServiceWrapper
Конструктор линейчатой TooltipServiceWrapper диаграммы теперь имеет элемент, который создается в конструкторе с экземпляром узла tooltipService .
private tooltipServiceWrapper: ITooltipServiceWrapper;
this.tooltipServiceWrapper = createTooltipServiceWrapper(this.host.tooltipService, options.element);
Класс TooltipServiceWrapper содержит tooltipService экземпляр, а также в качестве корневого элемента D3 параметров визуального и сенсорного элемента.
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;
}
.
.
.
}
Одна точка входа для этого класса для регистрации прослушивателей событий — addTooltip это метод.
Метод 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. Элемент> выбора<: элементы d3, над которыми обрабатываются подсказки.
- getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: делегат для заполнения содержимого подсказки (что нужно отобразить) для каждого контекста.
- getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: делегат для получения идентификатора точки данных (неиспользуемого в этом примере).
- reloadTooltipDataOnMouseMove? логическое значение: логическое значение, указывающее, следует ли обновлять всплывающие данные во время события MouseMove (неиспользуемого в этом примере).
Как видно, выход без действия, addTooltip если tooltipService отключен или нет реального выбора.
Вызов метода show для отображения подсказки
Следующий addTooltip метод прослушивает событие D3 mouseover , как показано в следующем коде:
...
...
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: извлекает контекст из выбранных элементов D3 в подсказкуEventArgs. Он также вычисляет координаты.
- getTooltipInfoDelegate: затем он создает содержимое подсказки из подсказкиEventArgs. Это обратный вызов к классу BarChart, так как это логика визуального элемента. Это фактическое текстовое содержимое, отображаемое в подсказке.
- getDataPointIdentity: unused в этом примере.
- this.visualHostTooltipService.show: вызов отображения подсказки.
Дополнительную обработку можно найти в примере для mouseout событий и mousemove событий.
Дополнительные сведения см. в визуальном репозитории SampleBarChart.
Заполнение содержимого подсказки методом getTooltipData
Класс BarChart был добавлен с элементомgetTooltipData, который просто извлекает categoryvalueи color точку данных в элемент VisualTooltipDataItem[] .
private static getTooltipData(value: any): VisualTooltipDataItem[] {
return [{
displayName: value.category,
value: value.value.toString(),
color: value.color,
header: 'ToolTip Title'
}];
}
В предыдущей реализации header член является константой, но его можно использовать для более сложных реализаций, для которых требуются динамические значения. Вы можете заполнить VisualTooltipDataItem[] несколько элементов, которые добавляют несколько строк в подсказку. Это может быть полезно в визуальных элементах, таких как гистограммы с накоплением, в которых подсказка может отображать данные из нескольких точек данных.
Вызов метода addTooltip
Последним шагом является вызов addTooltip метода при изменении фактических данных. Этот вызов выполняется в методе BarChart.update() . Вызов выполняется для отслеживания выделения всех элементов панели, передавая только BarChart.getTooltipData()упоминание ранее.
this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
(tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
(tooltipEvent: TooltipEventArgs<number>) => null);
Добавление поддержки подсказок на страницу отчета
Чтобы добавить поддержку подсказок страниц отчета (возможность изменять подсказки в области форматирования страницы отчета), добавьте tooltipsобъект в файл capabilities.json .
Например:
{
"tooltips": {
"supportedTypes": {
"default": true,
"canvas": true
},
"roles": [
"tooltips"
]
}
}
Затем можно определить подсказки на панели форматирования страницы отчета.
supportedTypes: конфигурация подсказки, поддерживаемая визуальным элементом и отраженная в полях.default: указывает, поддерживается ли привязка "автоматических" подсказок через поле данных.canvas: указывает, поддерживаются ли подсказки страницы отчета.
roles: (Необязательно) После определения он указывает, какие роли данных привязаны к выбранному параметру подсказки в полях.
Дополнительные сведения см. в руководстве по использованию подсказок страниц отчета.
Чтобы отобразить подсказку страницы отчета, после вызова ITooltipService.Show(options: TooltipShowOptions) узла Power BI или ITooltipService.Move(options: TooltipMoveOptions)используется selectionId (identities свойство предыдущего options аргумента). Чтобы получить подсказку, SelectionId должен представлять выбранные данные (категории, серии и т. д.) элемента, на который наведен указатель мыши.
Пример отправки идентификатора selectionId в вызовы отображения подсказки показан в следующем коде:
this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
(tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
(tooltipEvent: TooltipEventArgs<number>) => tooltipEvent.data.selectionID);
Добавление поддержки современных подсказок на страницу отчета
Из API версии 3.8.3 можно также создать современные подсказки визуального элемента. Современные подсказки добавляют действия детализации точек данных в подсказки и обновляют стиль в соответствии с темой отчета. Чтобы узнать, какая версия используется, проверка apiVersion в файле pbiviz.json.
Чтобы управлять поддержкой современных подсказок страниц отчета, добавьте свойство в объект в файле capabilities.json.tooltipssupportEnhancedTooltips
Например:
{
"tooltips": {
... ,
"supportEnhancedTooltips": true
}
}
См. пример современных подсказок, используемых в коде SampleBarChart .
Примечание.
Добавление этой функции в файл capabilities.json дает пользователю возможность включить эту функцию для отчета. Помните, что пользователю по-прежнему придется включить современную функцию подсказки в параметрах отчета.