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

Улучшение взаимодействия пользователей с закладками

  • Статья

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

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

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

Заметка

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

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

Дополнительные сведения об использовании закладок в Power BI см. в статье Создание закладок в Power BI Desktop.

Сведения об использовании личных закладок при внедрении Power BI см. в разделе Личные закладки.

Использование закладок отчета

В следующих разделах показано, как использовать API клиента Power BI для работы с закладками отчетов.

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

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

Класс BookmarksManager имеет следующие методы:

  • getBookmarks. Возвращает список сохраненных закладок, связанных с отчетом.

  • apply. Применяется по имени ранее сохраненной закладки к отчету.

  • capture — записывает и возвращает строку сериализации base64, которая представляет текущее состояние отчета.

  • applyState применяет ранее записанное состояние сериализации base64 закладки к отчету.

  • play. Управляет режимом презентации слайд-шоу для закладок отчета.

Доступ к закладке отчета

Чтобы получить доступ к отдельной закладке, используйте метод getBookmarks для доступа к списку объектов ReportBookmark. Класс ReportBookmark имеет следующие свойства:

  • name — уникальный идентификатор закладки отчета.

  • displayName — отображаемое имя закладки отчета, которое отображается в области закладки.

  • state — сериализация состояния закладки отчета base64. Его можно сохранить и применить к отчету с помощью метода bookmarksManager.applyState.

  • children — список объектов ReportBookmark, представляющих группу закладок отчета, если она существует.

Использование API закладок отчета

В внедренном отчете разработчики могут:

Получение списка сохраненных закладок отчета

Чтобы получить список сохраненных закладок, связанных с отчетом, вызовите метод getBookmarks объекта BookmarksManager, возвращаемого свойством bookmarksManager отчета.

Метод getBookmarks определяется следующим образом:

getBookmarks(): Promise<models.IReportBookmark[]>

Например:

let bookmarks = await report.bookmarksManager.getBookmarks();

Применение сохраненной закладки по имени при загрузке отчета или во время сеанса

Чтобы применить ранее сохраненную закладку к отчету с помощью его имени закладки, вызовите метод apply объекта BookmarksManager, возвращаемого свойством bookmarksManager отчета.

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

Метод apply определяется следующим образом:

apply(bookmarkName: string): Promise<void>

Например:

await report.bookmarksManager.apply("Bookmark1234");

Захват и получение текущего представления в виде объекта закладки

Чтобы записать текущее состояние отчета в виде строки base64, вызовите метод capture объекта BookmarksManager. Метод capture возвращает объект IReportBookmark, представляющий закладку, которая не сохраняется в определенном отчете. Используйте свойство IReportBookmark.state, чтобы вернуть строку base64, определяющую состояние закладки, которое можно позже применить к отчету во время загрузки или во время выполнения.

Метод capture определяется следующим образом:

capture(options?:ICaptureBookmarkOptions): Promise<models.IReportBookmark>

Например:

let capturedBookmark = await report.bookmarksManager.capture();

Параметры закладки для записи

Можно также передать объект ICaptureBookmarkOptions методу capture.

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages . По умолчанию записанное состояние закладки сохранит только текущее состояние страницы. Чтобы записать состояние всех страниц, вызовите метод capture с параметром allPages для параметра true.
  • personalizeVisuals. Чтобы записать текущее состояние с помощью персонализированных визуальных элементов, вызовите метод capture с параметром personalizeVisuals для параметра true.

Например, следующий код фиксирует состояние всех страниц, включая персонализированные визуальные элементы:

let capturedBookmark = await report.bookmarksManager.capture({
    allPages: true,
    personalizeVisuals: true
});

Применение захваченного состояния закладки при загрузке отчета или во время сеанса

Чтобы применить ранее записанное состояние закладки к отчету, используйте метод applyState объекта BookmarksManager.

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

Метод applyState определяется следующим образом:

applyState(state: string): Promise<void>

Например:

await report.bookmarksManager.applyState(capturedBookmark.state);

Выполнение дополнительной логики при применении закладки отчета

Чтобы определить, когда была применена закладка отчета, прослушивайте событие bookmarkApplied путем вызова метода on объекта отчета.

Например:

report.on("bookmarkApplied", (event) => {
    console.log(event.detail.name);
});

Отображение или скрытие области закладок

Чтобы отобразить или скрыть панель закладки Power BI, обновите свойство параметров отчета.

Отображение области "Закладки"

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: true
        }
    }
};

Скрытие области закладок

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: false
        }
    }
};

Сведения об обновлении параметров отчета см. в разделе Настройка параметров отчета.

Ввод или выход из режима слайд-шоу закладок

Чтобы управлять режимом презентации слайд-шоу для закладок отчета, вызовите метод play объекта BookmarksManager. Дополнительные сведения см. в разделе Закладки в виде слайд-шоу.

Метод play определяется следующим образом:

play(playMode: models.BookmarksPlayMode): Promise<void>

Заметка

Прежде чем вводить режим слайд-шоу закладок, убедитесь, что в отчете есть хотя бы одна закладка с API getBookmarks.

Ввод режима презентации слайд-шоу

await report.bookmarksManager.play(models.BookmarksPlayMode.Presentation);

Выход из режима презентации слайд-шоу

await report.bookmarksManager.play(models.BookmarksPlayMode.Off);

Рекомендации и ограничения

  • При использовании API закладок некоторые изменения отчета могут вызвать ошибку или непредвиденный результат. Одним из примеров этого является удаление фильтров отчетов из отчета. Чтобы избежать ошибок, должны присутствовать соответствующие карточки фильтров. Вместо удаления фильтров задайте для их значений значение All. Если вы не знаете, какие фильтры были удалены или изменены, повторно откройте закладку после применения изменений к отчету.

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

Связанное содержимое