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

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

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

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

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

Примечание

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

  • Powerbi-visuals-utils-interactivityutils версии 3.0.0 или более поздней для фильтрации визуальных элементов и любого визуального элемента, использующего InteractivityService.

  • API визуальных элементов версии 1.11.0 или более поздней для визуальных элементов без фильтра, которые используют SelectionManager вместо InteractivityService.

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

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

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

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

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

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

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

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

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

  • Если визуальный элемент использует InteractivityService для управления выбранными фрагментами, используйте applySelectionFromFilter. Это самый простой и предпочитаемый метод.

  • Если визуальный элемент не использует InteractivityService, примените SelectionManager.

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

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

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

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

Если вы не используете InteractivityService, можно сохранять и отзывать выбранные элементы закладки с помощью метода 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. Затем при отрисовке точек данных состояние выбора пользовательского визуального элемента будет соответствовать состоянию закладки.

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

Для поддержки закладок в визуальных элементах с фильтром необходимо использовать InteractivityService.

Предположим, что визуальный элемент создает фильтр данных по диапазону дат. 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
}

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

Важно!

В приведенном выше сценарии с закладками отчета визуальный элемент не должен вызывать applyJsonFilter для фильтрации других визуальных элементов. Они уже будут фильтроваться Power BI.

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

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

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

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

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

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

Дальнейшие действия