Partager via

Améliorer l’expérience de vos utilisateurs avec les 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 clientes Power BI pour capturer et appliquer des signets.

Un signet enregistré peut être un signet enregistré dans le cadre d’un rapport ou d’un signet capturé 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 ce 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.

Note

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 la vue de rapport 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.

Comment utiliser des signets de rapport

Les sections suivantes montrent comment utiliser les API clientes Power BI pour utiliser des signets de rapport.

Gérer les signets d’un rapport

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

La classe BookmarksManager a les méthodes suivantes :

  • getBookmarks : retourne une liste de signets enregistrés associés au rapport.

  • apply : s’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 en base64 capturé précédemment 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 méthode getBookmarks 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 d’affichage du signet de rapport, qui apparaît 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 méthode bookmarksManager.applyState.

  • 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 méthode getBookmarks de l’objet BookmarksManager retourné par la propriété bookmarksManager du rapport.

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

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

Par exemple:

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

Appliquer un signet enregistré par nom au 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 méthode apply de l’objet BookmarksManager retourné par la propriété bookmarksManager d’un rapport.

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

La méthode apply 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 sous la forme d’une chaîne base64, appelez la méthode capture d’un objet BookmarksManager. La méthode capture retourne un objet IReportBookmark, qui représente un signet qui n’est pas enregistré dans un rapport spécifique. Utilisez la propriété IReportBookmark.state pour renvoyer la chaîne base64 identifiant l’état du signet, que vous pouvez appliquer ultérieurement à un rapport pendant le temps de chargement ou l’heure d’exécution.

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

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

Par exemple:

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

Capturez les options de signet

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

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages - Par défaut, l’état du signet capturé enregistre uniquement l’état de la page active. Pour capturer l’état de toutes les pages, appelez capture méthode avec l’option allPages définie sur true.
  • personalizeVisuals : pour capturer l’état actuel avec visuels personnalisés, appelez la méthode capture 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 méthode applyState d’un objet BookmarksManager.

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

La méthode applyState 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 méthode on de l’objet rapport.

Par exemple:

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

Afficher ou masquer le volet Signets

Pour afficher ou masquer les signets Power BI volet, mettez à jour la propriété panes des paramètres de 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 méthode play d’un objet BookmarksManager. Pour plus d’informations, consultez Signets sous la forme d’un diaporama.

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

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

Note

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

Entrer le mode 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);

Considérations et limitations

  • Lorsque vous utilisez l’API signets, certaines modifications apportées au rapport peuvent entraîner une erreur ou un résultat inattendu. L’un des exemples suivants consiste à supprimer les filtres de rapport du rapport. 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, récapitulez 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 les filtres de mise à jour ajouter une opération, sont capturés dans l’état du signet, mais seront appliqués uniquement dans la session active. Pour surmonter cette limitation, le filtre doit être enregistré sur le rapport avec la valeur All et modifié dans la session incorporée à l’aide de l’opération de mise à jour des filtres de mise à jour .

Contenu connexe