Share via

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

  • Article

Les signets de rapport dans Power BI vous permettent de capturer l’état actuel d’une page de rapport incorporée, y compris tous les filtres et l’état de ses visuels. Lorsque vous ouvrez le rapport ultérieurement, vous pouvez sélectionner le signet pour restaurer le rapport à l’état enregistré. Les développeurs peuvent contrôler l’expérience utilisateur à l’aide des API du client Power BI pour capturer et appliquer des signets.

Un signet enregistré peut être un signet enregistré dans le cadre d’un rapport ou un signet capturé en tant qu’état en temps réel d’un rapport. Si vous appliquez un signet enregistré lorsque vous chargez un rapport, vous pouvez spécifier le signet à utiliser en fournissant le nom du signet ou son état. Si vous fournissez un signet par nom, votre rapport doit contenir un signet enregistré portant le même nom.

Cet article explique les différents paramètres d’API dont vous aurez besoin pour incorporer des rapports qui prennent en charge les signets.

Notes

Dans les rapports que vous incorporez pour votre organisation, les consommateurs de rapports créent des signets personnels en capturant l’état du rapport et en retournant rapidement à cet état en sélectionnant le signet. Pour plus d’informations, consultez Signets personnels .

Pour plus d’informations sur la création d’une expérience similaire dans les rapports que vous incorporez pour vos clients, consultez la présentation de l’affichage des rapports de capture dans le terrain de jeu d’analytique incorporée Power BI.

Pour plus d’informations sur l’utilisation de signets dans Power BI, consultez Créer des signets dans Power BI Desktop.

Pour plus d’informations sur l’utilisation de signets personnels lors de l’incorporation de Power BI, consultez Signets personnels.

Utilisation des signets de rapport

Les sections suivantes montrent comment utiliser les API du client Power BI pour utiliser les signets de rapport.

Gérer les signets d’un rapport

Pour gérer les signets d’un rapport, utilisez la bookmarksManager propriété d’une instance de rapport incorporée.

La classe BookmarksManager utilise les méthodes suivantes :

  • getBookmarks - Retourne une liste de signets enregistrés associés au rapport.

  • apply - Applique par nom un signet précédemment enregistré au rapport.

  • capture - Capture et retourne une chaîne de sérialisation en base64, qui représente l’état actuel du rapport.

  • applyState Applique un état de sérialisation base64 précédemment capturé d’un signet au rapport.

  • play - Contrôle le mode de présentation du diaporama pour les signets du rapport.

Accéder à un signet de rapport

Pour accéder à un signet individuel, utilisez la getBookmarks méthode pour accéder à une liste d’objets ReportBookmark . La classe ReportBookmark a les propriétés suivantes:

  • name - Identificateur unique du signet de rapport.

  • displayName - Nom complet du signet de rapport, qui s’affiche dans le volet Signets .

  • state - Sérialisation en base64 de l’état du signet de rapport. Vous pouvez l’enregistrer et l’appliquer à un rapport avec la bookmarksManager.applyState méthode .

  • children - Liste d’objets ReportBookmark représentant un groupe de signets de rapport, s’il existe.

Utiliser les API de signets de rapport

Dans un rapport incorporé, les développeurs peuvent :

Obtenir la liste des signets de rapport enregistrés

Pour obtenir la liste des signets enregistrés associés à un rapport, appelez la getBookmarks méthode de l’objet BookmarksManager retourné par la propriété du bookmarksManager rapport.

La getBookmarks méthode est définie comme suit :

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

Par exemple :

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

Appliquer un signet enregistré par nom lors du chargement du rapport ou pendant une session

Pour appliquer un signet précédemment enregistré à un rapport à l’aide de son nom de signet, appelez la apply méthode de l’objet BookmarksManager retourné par la propriété d’un bookmarksManager rapport.

Pour plus d’informations, consultez Configurer les paramètres de rapport.

La apply méthode est définie comme suit :

apply(bookmarkName: string): Promise<void>

Par exemple :

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

Capturer et obtenir une vue actuelle en tant qu’objet signet

Pour capturer l’état actuel d’un rapport en tant que chaîne base64, appelez la capture méthode d’un objet BookmarksManager . La capture méthode retourne un IReportBookmark objet, qui représente un signet qui n’est pas enregistré dans un rapport spécifique. Utilisez la IReportBookmark.state propriété pour renvoyer la chaîne base64 identifiant l’état de signet, que vous pouvez appliquer ultérieurement à un rapport au moment du chargement ou de l’exécution.

La capture méthode est définie comme suit :

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

Par exemple :

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

Options de signet de capture

Vous pouvez également passer un ICaptureBookmarkOptions objet à la capture méthode .

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages - Par défaut, l’état de signet capturé enregistre uniquement l’état de la page actuelle. Pour capturer l’état de toutes les pages, appelez capture la méthode avec l’option allPages définie sur true.
  • personalizeVisuals - Pour capturer l’état actuel avec des visuels personnalisés, appelez la capture méthode avec l’option personalizeVisuals définie sur true.

Par exemple, le code suivant capture l’état de toutes les pages, y compris les visuels personnalisés :

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

Appliquer un état de signet capturé lors du chargement du rapport ou pendant une session

Pour appliquer un état de signet précédemment capturé à un rapport, utilisez la applyState méthode d’un objet BookmarksManager .

Pour plus d’informations, consultez Configurer les paramètres de rapport.

La applyState méthode est définie comme suit :

applyState(state: string): Promise<void>

Par exemple :

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

Effectuer une logique supplémentaire lorsqu’un signet de rapport est appliqué

Pour déterminer quand un signet de rapport a été appliqué, écoutez l’événement bookmarkApplied en appelant la on méthode de l’objet de rapport .

Par exemple :

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

Afficher ou masquer le volet Signets

Pour afficher ou masquer le volet Signets Power BI, mettez à jour la panes propriété des paramètres du rapport.

Afficher le volet Signets

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

Masquer le volet Signets

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

Pour plus d’informations sur la mise à jour des paramètres de rapport, consultez Configurer les paramètres de rapport.

Entrer ou quitter le mode diaporama des signets

Pour contrôler le mode de présentation du diaporama pour les signets d’un rapport, appelez la play méthode d’un objet BookmarksManager . Pour plus d’informations, consultez Signets en tant que diaporama.

La play méthode est définie comme suit :

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

Notes

Avant d’entrer le mode diaporama des signets, assurez-vous qu’il existe au moins un signet sur le rapport avec l’API getBookmarks.

Entrer le mode de présentation du diaporama

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

Quitter le mode présentation du diaporama

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

Limites

  • Lorsque vous utilisez l’API signets, certaines modifications apportées au rapport peuvent provoquer une erreur ou un résultat inattendu. La suppression des filtres de rapport du rapport en est un exemple. Pour éviter les erreurs, les cartes de filtre correspondantes doivent être présentes. Au lieu de supprimer les filtres, définissez leurs valeurs sur All. Si vous ne savez pas quels filtres ont été supprimés ou modifiés, recapturez le signet après avoir appliqué les modifications au rapport.

  • Les filtres tels que sur les filtres de chargement créés par la session incorporée ou ajoutés par l’opération d’ajout de filtres de mise à jour, sont capturés dans l’état de signet, mais seront appliqués uniquement dans la session active. Pour surmonter cette limitation, le filtre doit être enregistré dans le rapport avec la All valeur et modifié dans la session d’incorporation à l’aide de l’opération de mise à jour des filtres de mise à jour.

Étapes suivantes