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

2025-04-03

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

Дополнительные сведения о закладках см. в статье "Использование закладок для совместного использования аналитических сведений и создания историй в Power BI".

Визуальные элементы, поддерживающие закладки

Визуальный элемент Power BI, поддерживающий закладки, должен иметь возможность сохранять и предоставлять правильные сведения при необходимости. Если визуальный элемент взаимодействует с другими визуальными элементами, выбирает точки данных или фильтрует другие визуальные элементы, необходимо сохранить состояние закладки в свойствах filterState визуального элемента.

Примечание.

Для создания визуального элемента, поддерживающего закладки, требуется:

Visual API версии 1.11.0 или более поздней для нефильтрованных визуальных элементов, использующих SelectionManager.
Visual API версии 2.6.0 или более поздней версии для визуальных элементов фильтрации.
Чтобы узнать, какая версия используется, проверьте apiVersion в файле pbiviz.json.

Взаимодействие визуальных элементов Power BI с Power BI в закладках отчетов

Предположим, вы хотите создать несколько закладок на странице отчета, в каждой из них выбраны разные точки данных.

Сначала выберите одну или несколько точек данных в визуальном элементе. Визуальный элемент передает ваш выбор хосту. Затем выберите Добавить в панели Закладка. Power BI сохраняет текущие выбранные элементы для новой закладки.

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

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

Новое состояние выбора (или фильтр) передается через options.jsonFilters свойство в методе update . Может быть jsonFilters либо Advanced Filter либо Tuple Filter.

Если ваш визуальный элемент содержит выбранные точки данных, сбросьте выделение согласно выбранной закладке, используя функцию обратного вызова registerOnSelectCallback в ISelectionManager.
Если ваш визуальный элемент использует фильтры для выбора данных, сбросьте значения фильтра до соответствующих значений выбранной закладки.

Изображения с выделением

Примечание.

InteractivityService устарел.

Если визуальный элемент взаимодействует с другими визуальными элементами с помощью выбора, можно добавить поддержку закладок одним из двух способов:

С помощью InteractivityService для управления выборами используйте параметр applySelectionFromFilter. Это нерекомендуемый метод.
Через SelectionManager.

Использование InteractivityService для восстановления выбранных закладок — не рекомендуется

Если визуальный элемент использует InteractivityService, вам не нужны другие действия для поддержки закладок в визуальном элементе.

При выборе закладки программа автоматически обрабатывает состояние выбора визуального элемента.

Восстановление выбранных закладок с помощью SelectionManager

Вы можете сохранить и отозвать выбор закладок с помощью ISelectionManager.registerOnSelectCallback метода следующим образом:

При выборе закладки Power BI вызывает метод callback визуализации с соответствующими выбранными элементами.

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        //called when a selection was set by Power BI
    });
);

Предположим, что в методе visualTransform вашего визуального элемента вы создали точку данных.

Выглядит datapoints следующим образом:

visualDataPoints.push({
    category: categorical.categories[0].values[i],
    color: getCategoricalObjectValue<Fill>(categorical.categories[0], i, 'colorSelector', 'fill', defaultColor).solid.color,
    selectionId: host.createSelectionIdBuilder()
        .withCategory(categorical.categories[0], i)
        .createSelectionId(),
    selected: false
});

Теперь у вас есть visualDataPoints в качестве точек данных и массив ids, переданный функции callback.

На этом этапе визуальный элемент должен сравнить массив ISelectionId[] с выборами в массиве visualDataPoints, а затем пометить соответствующие точки данных как выбранные.

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        visualDataPoints.forEach(dataPoint => {
            ids.forEach(bookmarkSelection => {
                if (bookmarkSelection.equals(dataPoint.selectionId)) {
                    dataPoint.selected = true;
                }
            });
        });
    });
);

После обновления точек данных они будут отражать текущее состояние выбора, хранящееся в объекте filter . Затем при отрисовке точек данных состояние выбора пользовательской визуализации соответствует состоянию закладки.

Визуальные элементы с фильтром

Предположим, что визуальный элемент создает фильтр данных по диапазону дат. У вас есть startDate и endDate даты начала и окончания диапазона.

Визуальный элемент создает расширенный фильтр и вызывает метод applyJsonFilter хоста для фильтрации данных по релевантным условиям.

Целевой объект — это таблица, используемая для фильтрации.

import { AdvancedFilter } from "powerbi-models";

const filter: IAdvancedFilter = new AdvancedFilter(
    target,
    "And",
    {
        operator: "GreaterThanOrEqual",
        value: startDate
            ? startDate.toJSON()
            : null
    },
    {
        operator: "LessThanOrEqual",
        value: endDate
            ? endDate.toJSON()
            : null
    });

this.host.applyJsonFilter(
    filter,
    "general",
    "filter",
    (startDate && endDate)
        ? FilterAction.merge
        : FilterAction.remove
);

Каждый раз при выборе закладки пользовательский визуальный элемент получает вызов функции update.

В методе визуальный update элемент проверяет фильтр в объекте:

const filter: IAdvancedFilter = FilterManager.restoreFilter(
    && options.jsonFilters
    && options.jsonFilters[0] as any
) as IAdvancedFilter;

filter Если объект не имеет значения NULL, визуальный элемент восстанавливает условия фильтра из объекта:

const jsonFilters: AdvancedFilter = this.options.jsonFilters as AdvancedFilter[];

if (jsonFilters
    && jsonFilters[0]
    && jsonFilters[0].conditions
    && jsonFilters[0].conditions[0]
    && jsonFilters[0].conditions[1]
) {
    const startDate: Date = new Date(`${jsonFilters[0].conditions[0].value}`);
    const endDate: Date = new Date(`${jsonFilters[0].conditions[1].value}`);

    // apply restored conditions
} else {
    // apply default settings
}

После этого визуализация изменяет свое внутреннее состояние в соответствии с текущими условиями. Внутреннее состояние включает точки данных и объекты визуализации (линии, прямоугольники и т. д.).

Визуальный элемент "Срез временной шкалы" изменяет селектор диапазона на соответствующие диапазоны данных.

Сохранить состояние фильтра визуала

Помимо сохранения условий фильтра для закладки, можно также сохранить другие аспекты фильтра.

Например, компонент Срез временной шкалы сохраняет значения свойств Granularity в качестве состояния фильтра. Она позволяет детализировать временную шкалу (дни, месяцы, годы и т. д.) при изменении закладок.

Свойство filterState сохраняет аспект фильтра в качестве свойства. Визуальный компонент может хранить различные filterState значения в закладках.

Чтобы сохранить значение свойства в качестве состояния фильтра, задайте свойство объекта как "filterState": true в файле capabilities.json .

Поделиться через