Бөлісу құралы:

Добавление подсказок в визуальные элементы Power BI

  • Мақала

Подсказки — это элегантный способ предоставления более контекстной информации и подробных сведений точкам данных на визуальном элементе. API подсказок Power BI может обрабатывать следующие взаимодействия:

  • Отображение подсказки.
  • Скрытие подсказки.
  • Перемещение подсказки.

Подсказки могут отображать текстовый элемент с заголовком, значением заданного цвета и непрозрачностью в указанном наборе координат. Эти данные предоставляются API, а узел Power BI отрисовывает его так же, как и подсказки для собственных визуальных элементов.

Вы можете изменить стиль подсказок или добавить действия бурения, включив современные подсказки .

На следующем рисунке показана подсказка в примере линейчатой диаграммы:

Screenshot that shows sample bar chart tooltips.

На приведенном выше рисунке подсказки показана одна линейчатая категория и значение. Вы можете расширить подсказку для отображения нескольких значений.

Управление подсказками

Подсказки в визуальном элементе 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: (Необязательно) После определения он указывает, какие роли данных привязаны к выбранному параметру подсказки в полях.

Screenshot that shows the Report page tooltip dialog.

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

Чтобы отобразить подсказку страницы отчета, после вызова 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.

Screenshot that shows a modern tooltip.

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

Например:

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

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

Примечание.

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

Связанный контент

Подсказки дляutils

Настройка подсказок в Power BI

Создание подсказок на основе страниц отчетов в Power BI Desktop