Добавление подсказок в визуальные элементы 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.Selection<Элемент>: Элементы d3, над которыми обрабатываются всплывающие подсказки.
getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: делегат для заполнения содержимого подсказки (что нужно отобразить) для каждого контекста.
getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: делегат для получения идентификатора точки данных (неиспользуемого в этом примере).
reloadTooltipDataOnMouseMove? логическое значение: логическое значение, указывающее, следует ли обновлять данные подсказки во время события MouseMove (неиспользуемого в этом примере).

Как видно, addTooltip происходит без действия, если tooltipService отключен или нет реального выбора.

Следующий 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 в TooltipEventArgs. Он также вычисляет координаты.
getTooltipInfoDelegate: затем он создает содержимое подсказки из tooltipEventArgs. Это функция обратного вызова к классу BarChart, потому что она отвечает за логику визуализации. Это фактическое текстовое содержимое, отображаемое в подсказке.
getDataPointIdentity: неиспользованный в этом примере.
this.visualHostTooltipService.show: вызов отображения подсказки.

Дополнительную обработку можно найти в примере для событий mouseout и mousemove.

Для получения дополнительной информации см. визуальный ресурс SampleBarChart.

Класс BarChart был добавлен с элементом getTooltipData, который просто извлекает category, value, и 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() . Вызов выполняется для отслеживания выделения всех элементов «bar», передавая только 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) или ITooltipService.Move(options: TooltipMoveOptions) хоста Power BI используется 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 .

Снимок экрана, на котором показана современная всплывающая подсказка.

Чтобы управлять поддержкой современных всплывающих подсказок для страниц отчета, добавьте свойство supportEnhancedTooltips в объект tooltips в файле capabilities.json.

Например:

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

См. пример современных подсказок, используемых в коде SampleBarChart .

Примечание.

Добавление этой функции в файл capabilities.json дает пользователю возможность включить эту функцию для отчета.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-12-15