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

  • Статья

Закладки отчетов в 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, обновите panes свойство параметров отчета.

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

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 и изменен в сеансе внедрения с помощью операции обновления фильтров обновления.

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