Настройка параметров отчета

Статья
07/15/2024

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

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

Помимо предоставления api-доступа к отчету, можно также использовать объект конфигурации для настройки внешнего вида и поведения отчета. Например, можно настроить видимость фильтра, доступ к навигации и параметры расположения в объекте конфигурации.

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

Укажите сведения о конфигурации

Интерфейс IReportLoadConfiguration отображает свойства, которые объект конфигурации может предоставить API клиента Power BI для отчета:

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

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

Настройка параметров

В следующих разделах описывается, как использовать свойство settings для настройки внешнего вида и поведения внедренного отчета Power BI. Чтобы обновить параметры отчета при загрузке отчета, используйте метод report.updateSettings. Дополнительные сведения см. в разделе Обновление параметров отчета во время выполнения.

Панели

Управление внешним видом всех панелей в отчете Power BI с помощью одного свойства panes, как показано в следующем коде:

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

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

Свойство	Видимый	Расширенный
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

Область фильтра

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

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

Заметка

Свойство панели заменяет свойство filterPaneEnabled. Для обеспечения обратной совместимости свойство filterPaneEnabled по-прежнему существует. Однако следует избегать использования этих двух свойств вместе.

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

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

Заметка

Свойство панели заменяет свойство navContentPaneEnabled. Для обеспечения обратной совместимости свойство navContentPaneEnabled по-прежнему существует. Однако следует избегать использования этих двух свойств вместе.

Область навигации по страницам отображается в нижней части отчета, чтобы использовать новую область вертикальных страниц, можно задать свойство position:

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

Заметка

Невозможно изменить положение области навигации страницы с помощью updateSettings.

Баров

Задайте видимость панели действий и строки состояния с помощью свойства bars.

Панель действий

Следующий код делает панель действий видимой:

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

Кроме того, в режиме просмотра также можно использовать параметр URL-адреса actionBarEnabled:

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

Заметка

В режиме просмотра панель действий поддерживается только для внедрения для сценария организации.

Для панели действий в режиме просмотра рекомендуется включить разрешение UserState.ReadWrite.All для приложения Azure AD. Это разрешение необходимо, чтобы конечные пользователи могли добавлять отчет в избранное, а также для включения личных закладок и постоянных фильтров.

Строка состояния

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

Следующий код делает строку состояния видимой:

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

Параметры языкового стандарта

Используйте свойство localeSettings, чтобы указать язык и форматирование внедренного отчета:

Свойство language в localeSettings состоит из двух частей двух букв, разделенных дефисом:

язык определяет язык, который Power BI использует для локализации. Примеры языков: en (английский), es (испанский) и tr (турецкий).
языковой стандарт определяет форматирование текста, которое Power BI использует для дат, валют и другого связанного содержимого. Примерами языковых стандартов являются США (английский), ES (Испания) и TR (Türkiye).

Список доступных языков и регионов см. в поддерживаемых языков.

Следующий код назначает определенные значения этим localeSettings:

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

Заметка

Параметры языкового стандарта нельзя изменить после загрузки отчета. Чтобы изменить параметры языкового стандарта отчета, сбросить iframe, вызвав powerbi.reset(element), а затем снова внедрить отчет.

Прозрачный фон

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

Используйте этот код, чтобы сделать фон внедренного содержимого прозрачным:

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

Поведение щелчка гиперссылки

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

Доступные режимы поведения:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate . URL-адрес загружается в новый контекст просмотра.
NavigateAndRaiseEvent — URL-адрес загружается в новый контекст просмотра и вызывает событие dataHyperlinkClicked.
RaiseEvent. Предотвращает поведение по умолчанию щелчка URL-адреса и вызывает событие dataHyperlinkClicked.

Используйте этот код для изменения поведения ссылок, чтобы вызвать событие:

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

Событие dataHyperlinkClicked возникает, когда гиперссылка щелкается на визуальных элементах таблицы или матрицы, а поведение — NavigateAndRaiseEvent или RaiseEvent.

report.on('dataHyperlinkClicked', () => {
    ...
});

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

Визуальная отрисовка событий

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

Используйте этот код для активации событий visualRendered:

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

Событие visualRendered запускается при отрисовки визуального элемента, а visualRenderedEvents включен в параметрах отчета.

report.on('visualRendered', () => {
    ...
});

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

Заметка

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

Сообщения об ошибках

Если вы хотите отобразить настраиваемые сообщения об ошибках в внедренных отчетах, используйте свойство hideErrors, чтобы скрыть сообщения об ошибках Power BI embedded по умолчанию. Затем код может обрабатывать события ошибок таким образом, чтобы он соответствовал дизайну приложения. Дополнительные сведения об переопределении ошибок по умолчанию см. в об переопределении ошибок по умолчанию.

Используйте этот код для скрытия сообщений об ошибках по умолчанию:

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

Настройка параметров

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

Страница по умолчанию

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

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

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

При загрузке фильтров

Вы можете управлять фильтрами, которые приложение применяет к внедренным отчетам. По умолчанию отчет изначально использует фильтры, сохраненные в отчете. Однако у вас есть два варианта, если вы хотите настроить фильтры:

Настройте дополнительные фильтры для использования вместе с сохраненными фильтрами. В следующем коде показано, как использовать свойство filters для добавления дополнительных фильтров:
```
let embedConfig = {
    ...
    filters: [...]
};
```
Замените сохраненные фильтры новым набором. Метод setFilters позволяет динамически изменять фильтры отчета. При использовании этого метода во время поэтапного внедрения можно переопределить фильтры, которые изначально применяется отчет. Дополнительные сведения о создании фильтров и использовании метода setFilters см. в фильтрах отчетов control.

При загрузке срезов

Вы можете управлять состоянием срезов, которые приложение применяет к внедренным отчетам. По умолчанию API использует срезы, сохраненные в отчете. Однако для изменения состояния существующих срезов можно использовать свойство slicers, как показано в следующем коде:

embedConfig = {
    ...
    slicers: slicerArray,
};

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

При загрузке закладки

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

Закладку можно указать, указав имя закладки или состояние. Если указать имя закладки, отчет Power BI должен содержать сохраненную закладку с таким именем.

Свойство bookmark имеет тип IApplyBookmarkRequest. В следующем коде показано определение этого типа:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

В этом коде показано, как указать закладку по имени:

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

В этом коде показано, как указать закладку по состоянию:

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

Темы и режим высокой контрастности

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

Доступные режимы контрастности:

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

Чтобы настроить определенную тему, используйте код, аналогичный следующим строкам:

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

В следующем коде показано, как переопределить уровень контрастности по умолчанию, None:

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

Заметка

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

Уровень масштабирования

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

Открытие в режиме редактирования

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

Настройка режима редактирования

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

Свойство viewMode можно назначить следующим образом:

View. Открывает отчет в режиме просмотра.
Edit. Открывает отчет в режиме редактирования.

Эти значения можно назначить permissions свойству:

Read. Пользователи могут просматривать отчет.
ReadWrite. Пользователи могут просматривать, изменять и сохранять отчет.
Copy. Пользователи могут сохранить копию отчета с помощью сохранить как.
Create . Пользователи могут создать новый отчет.
All. Пользователи могут создавать, просматривать, изменять, сохранять и сохранять копию отчета.

При настройке содержимого для открытия в режиме редактирования назначьте свойство permissions значение, подходящее для редактирования, как показано в следующем коде:

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

Заметка

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

Переключение между режимами редактирования и просмотра

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

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

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

Если содержимое находится в режиме просмотра и хотите переключиться в режим редактирования, используйте этот код JavaScript:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

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

Настройка параметров отчета

Укажите сведения о конфигурации

Настройка параметров

Панели

Область фильтра

Панель навигации по страницам

Баров

Панель действий

Строка состояния

Параметры языкового стандарта

Прозрачный фон

Поведение щелчка гиперссылки

Визуальная отрисовка событий

Сообщения об ошибках

Настройка параметров

Страница по умолчанию

При загрузке фильтров

При загрузке срезов

При загрузке закладки

Темы и режим высокой контрастности

Уровень масштабирования

Открытие в режиме редактирования

Настройка режима редактирования

Переключение между режимами редактирования и просмотра

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

Дополнительные ресурсы

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

Настройка параметров отчета

Укажите сведения о конфигурации

Настройка параметров

Панели

Область фильтра

Панель навигации по страницам

Баров

Панель действий

Строка состояния

Параметры языкового стандарта

Прозрачный фон

Поведение щелчка гиперссылки

Визуальная отрисовка событий

Сообщения об ошибках

Настройка параметров

Страница по умолчанию

При загрузке фильтров

При загрузке срезов

При загрузке закладки

Темы и режим высокой контрастности

Уровень масштабирования

Открытие в режиме редактирования

Настройка режима редактирования

Переключение между режимами редактирования и просмотра

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

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

Дополнительные ресурсы