Utiliser l’incorporation par phases

Article
09/22/2023

L’analytique powerbi.load et report.render les API incorporées Power BI peuvent améliorer l’expérience de l’utilisateur final en donnant aux développeurs plus de flexibilité pour l’incorporation de rapports de phase.

Normalement, vous chargez un rapport incorporé à l’aide de powerbi.embed:

let report = powerbi.embed(embedContainer, embedConfig);

Le rapport incorporé se charge et s’affiche dans l’interface utilisateur. L’utilisateur final voit ensuite toutes les interactions avec le rapport rendu. Par exemple, si vous appliquez un état de segment, l’utilisateur final voit le segment prendre effet après le rendu du rapport.

Pour masquer ces interactions aux utilisateurs finaux, les powerbi.load API et report.render décomposent le processus d’incorporation en phases. La powerbi.load fonction charge le rapport afin que vous puissiez interagir avec les éléments avant que les utilisateurs finaux voient les résultats. La report.render fonction affiche ensuite le rapport.

Load

La powerbi.load fonction charge le rapport, mais ne l’affiche pas, de sorte que des interactions peuvent se produire avant que l’utilisateur final ne voit les résultats. Par exemple, vous pouvez utiliser powerbi.load avec report.getPages, puis spécifier la page à afficher à l’utilisateur final. Vous pouvez également utiliser page.getVisuals, puis décider quels visuels afficher ou masquer.

Comme powerbi.embed, la powerbi.load fonction nécessite un élément HTML et un objet IEmbedConfiguration .

Une fois le chargement terminé, un loaded événement se déclenche.

let config = {
    ...
};

// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];

// Load the report in the container.
let report = powerbi.load(embedContainer, config);

report.on('loaded', function() {
    ...
});

Rendu

Si vous utilisez powerbi.load, vous devez ensuite appeler la report.render fonction sur la loaded fonction de gestionnaire d’événements, après avoir exécuté votre code. Utilisez report.render pour continuer le rendu du rapport et afficher le rapport incorporé.

Un rendered événement se déclenche lorsque le rendu du rapport est terminé.

report.on('loaded', function() {
    report.render();
});

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

Pour plus d’informations sur la gestion des événements, consultez Comment gérer les événements.

Exemple

L’exemple de code suivant charge un rapport, définit des filtres, puis restitue le rapport filtré.

// Build the config object.
let config = {
    type: 'report',
    tokenType: TokenType.Embed,
    accessToken: ...,
    embedUrl: ...,
    id: ...,
    ...
};
 
// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];

// Load the report in the container.
let report = powerbi.load(embedContainer, config);

...
report.on('loaded', async () => {
    await report.setFilters(filters);
    report.render();
});

Limites

L’incorporation progressive peut ralentir le rendu des rapports. Veillez donc à l’utiliser correctement et uniquement lorsque vous en avez besoin.

Vous pouvez appeler les API suivantes après avoir chargé le rapport et avant d’appeler report.render:

Méthode	Action
BookmarksManager.getBookmarks, BookmarksManager.apply	Obtenir et appliquer des signets. La capture de signets n’est pas prise en charge.
Report.updateSettings	Mettez à jour les paramètres du rapport.
Report.applyTheme	Appliquez le thème du rapport.
Report.getFilters, Report.setFilters, Report.removeFilters	Obtenir, définir et supprimer des filtres de rapport.
Report.getPages	Obtenez les pages de rapport.
Page.setActive	Définissez la page de rapport active.
Page.getFilters, Page.setFilters, Page.removeFilters	Obtenir, définir et supprimer des filtres de page.
Page.getVisuals	Obtenir des visuels de page.
Visual.getFilters, Visual.setFilters, Visual.removeFilters	Obtenir, définir et supprimer des filtres visuels.
Visual.getSlicerState, Visual.setSlicerState	Obtenir et définir l’état du segment visuel.

Étapes suivantes

Améliorer l’expérience de vos utilisateurs avec des signets

Appliquer des thèmes de rapport dans Power BI

Contrôler les filtres de rapport

Contrôler les segments de rapport

Obtenir des pages et des visuels

Partager via