Configurer les paramètres de rapport

  • Article

À l’aide des API du client Power BI, vous pouvez incorporer Power BI Analytics dans votre application. Lorsque vous utilisez cette bibliothèque côté client pour incorporer un rapport Power BI, vous fournissez à l’API des informations sur ce rapport.

Vous pouvez utiliser un objet de configuration pour stocker des informations sur votre rapport Power BI. Lorsque vous incorporez le rapport, vous passez ensuite cet objet à l’API.

En plus de donner à l’API l’accès au rapport, vous pouvez également utiliser l’objet de configuration pour personnaliser l’apparence et le comportement de votre rapport. Par instance, vous pouvez ajuster les paramètres de visibilité du filtre, d’accès de navigation et d’emplacement dans l’objet de configuration.

Les sections suivantes expliquent comment incorporer et configurer du contenu Power BI.

Fournir des informations de configuration

L’interface IReportLoadConfiguration affiche les propriétés qu’un objet de configuration peut fournir aux API du client Power BI à propos d’un rapport :

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;
}

Pour obtenir une explication des paramètres requis de cette interface, consultez Incorporer un rapport et pour obtenir des exemples de code montrant comment incorporer un rapport.

Personnaliser les paramètres

Les sections suivantes décrivent comment utiliser la settings propriété pour ajuster l’apparence et le comportement de votre rapport Power BI incorporé. Pour mettre à jour les paramètres du rapport lorsque le rapport est déjà chargé, utilisez la report.updateSettings méthode . Pour plus d’informations, consultez Mettre à jour les paramètres de rapport au moment de l’exécution.

Volets

Contrôlez l’apparence de tous les volets de votre rapport Power BI avec une seule panes propriété, comme indiqué dans le code suivant :

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
            }
        }
    }
};

Dans le tableau suivant, vous pouvez voir les valeurs que chaque panes propriété prend en charge :

Propriété Visible Développé
bookmarks ✔ ❌
fields ✔ ✔
filters ✔ ✔
pageNavigation ✔ ❌
selection ✔ ❌
syncSlicers ✔ ❌
visualizations ✔ ✔

Volet Filtre

Par défaut, le volet de filtre est visible. Si vous souhaitez masquer ce volet, utilisez la filterPaneEnabled propriété, comme indiqué dans le code suivant :

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

Notes

La propriété panes remplace la filterPaneEnabled propriété . Pour maintenir la compatibilité descendante, la filterPaneEnabled propriété existe toujours. Toutefois, vous devez éviter d’utiliser ces deux propriétés ensemble.

Volet de navigation de page

Par défaut, les flèches de navigation de page sont visibles dans les rapports incorporés. Pour masquer ces flèches, utilisez la navContentPaneEnabled propriété, comme indiqué dans le code suivant :

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

Notes

La propriété panes remplace la navContentPaneEnabled propriété . Pour maintenir la compatibilité descendante, la navContentPaneEnabled propriété existe toujours. Toutefois, vous devez éviter d’utiliser ces deux propriétés ensemble.

Le volet de navigation de page s’affiche en bas du rapport. Pour utiliser le nouveau volet pages verticales, vous pouvez définir la position propriété :

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

Notes

Vous ne pouvez pas modifier la position du volet de navigation de page à l’aide de updateSettings.

Bars

Définissez la visibilité de la barre d’actions et de status barre à l’aide de la bars propriété .

Barre d’actions

Le code suivant rend la barre d’action visible :

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

Vous pouvez également utiliser le actionBarEnabled paramètre URL en mode affichage :

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

Notes

En mode affichage, la barre d’actions est uniquement prise en charge pour l’incorporation pour votre scénario organization.

Pour la barre d’actions en mode affichage, il est recommandé d’activer UserState.ReadWrite.All l’autorisation pour votre application Azure AD. Cette autorisation est requise pour permettre aux utilisateurs finaux d’ajouter le rapport à leurs favoris et pour activer les signets personnels et lesfiltres persistants.

Barre d'état

La barre de status contient le contrôleur de zoom du canevas, ce qui permet de zoomer sur le canevas.

Le code suivant rend la barre status visible :

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

Paramètres régionaux

Utilisez la localeSettings propriété pour spécifier la langue et la mise en forme du rapport incorporé :

La language propriété dans localeSettings se compose de deux parties de deux lettres chacune, séparées par un trait d’union :

  • language définit la langue utilisée par Power BI pour la localisation. Les langues en (anglais), es (espagnol) et tr (turc) sont des exemples de langues.
  • les paramètres régionaux définissent la mise en forme du texte que Power BI utilise pour les dates, la devise et d’autres contenus associés. Parmi les exemples de paramètres régionaux, citons US (Anglais), ES (Espagne) et TR (Türkiye).

Consultez Langues prises en charge pour obtenir la liste des langues et régions disponibles.

Le code suivant affecte une valeur spécifique à ces valeurs localeSettings:

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

Notes

Les paramètres régionaux ne peuvent pas être modifiés une fois le rapport chargé. Pour modifier les paramètres régionaux du rapport, réinitialisez l’iframe en appelant powerbi.reset(element), puis incorporez à nouveau le rapport.

Arrière-plan transparent

Par défaut, l’arrière-plan du contenu incorporé est blanc avec des marges grises. Si vous préférez, vous pouvez donner au contenu incorporé un arrière-plan transparent. Vous pouvez ensuite appliquer le style souhaité à l’élément HTML div qui contient le contenu incorporé. Le div style de l’élément devient alors visible.

Utilisez ce code pour rendre l’arrière-plan du contenu incorporé transparent :

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

Vous pouvez contrôler le comportement d’un lien hypertexte dans une table ou des visuels de matrice prêtes à l’emploi. Par défaut, le lien hypertexte ouvre une nouvelle fenêtre.

Les modes de comportement disponibles sont répertoriés ci-dessous :

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}
  • Navigate - L’URL sera chargée dans un nouveau contexte de navigation.
  • NavigateAndRaiseEvent - L’URL est chargée dans un nouveau contexte de navigation et déclenche un dataHyperlinkClicked événement.
  • RaiseEvent - Empêche le comportement par défaut du clic sur l’URL et de l’événement déclencher dataHyperlinkClicked .

Utilisez ce code pour modifier le comportement des liens afin de déclencher un événement :

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

Un dataHyperlinkClicked événement se déclenche lorsqu’un lien hypertexte est cliqué sur un visuel de table ou de matrice prête à l’emploi et que le comportement est ou RaiseEventNavigateAndRaiseEvent .

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

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

Événements rendus visuels

Vous pouvez écouter un événement pour chaque visuel rendu. Par défaut, les événements rendus visuels sont désactivés.

Utilisez ce code pour déclencher les visualRendered événements :

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

Un visualRendered événement se déclenche lorsqu’un visuel est rendu et que le visualRenderedEvents est activé sur les paramètres du rapport.

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

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

Notes

Étant donné que les visuels peuvent s’afficher en raison d’interactions utilisateur, il est recommandé d’activer cet événement uniquement en cas de besoin.

Messages d’erreur

Si vous souhaitez afficher des messages d’erreur personnalisés dans des rapports incorporés, utilisez la hideErrors propriété pour masquer les messages d’erreur incorporés Power BI par défaut. Votre code peut ensuite gérer les événements d’erreur d’une manière adaptée à votre conception d’application. Pour plus d’informations sur le remplacement des erreurs par défaut, consultez Remplacer les messages d’erreur par défaut .

Utilisez ce code pour masquer les messages d’erreur par défaut :

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

Personnaliser les options

Les sections suivantes décrivent comment utiliser des propriétés supplémentaires pour personnaliser davantage l’apparence et le comportement de votre rapport Power BI incorporé.

Page par défaut

Vous pouvez contrôler la page de votre rapport incorporé qui s’affiche initialement. Par défaut, la page initiale est la page que vous avez modifiée le plus récemment, qui était la page active la dernière fois que vous avez enregistré le rapport. Vous pouvez remplacer ce comportement en utilisant la pageName propriété et en lui fournissant le nom de la page que vous souhaitez afficher. Toutefois, si aucune page portant ce nom n’existe dans Power BI, la demande d’ouverture échoue.

Le code suivant montre comment configurer votre application pour afficher une page spécifique :

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

Sur les filtres de charge

Vous pouvez contrôler les filtres que votre application applique à un rapport incorporé. Par défaut, le rapport utilise initialement les filtres que vous avez enregistrés dans le rapport. Toutefois, vous avez deux options si vous souhaitez ajuster les filtres :

  • Configurez des filtres supplémentaires à utiliser avec les filtres enregistrés. Le code suivant montre comment utiliser la filters propriété pour ajouter des filtres supplémentaires :

    let embedConfig = {
    ...
    filters: [...]
};

  • Remplacez les filtres enregistrés par un nouvel ensemble. La setFilters méthode permet de modifier dynamiquement les filtres d’un rapport. Si vous utilisez cette méthode lors de l’incorporation par phases, vous pouvez remplacer les filtres initialement appliqués par le rapport. Pour plus d’informations sur la construction de filtres et l’utilisation de la setFilters méthode , consultez Contrôler les filtres de rapport.

Sur les segments de charge

Vous pouvez contrôler l’état des segments que votre application applique à un rapport incorporé. Par défaut, l’API utilise les segments que vous avez enregistrés dans le rapport. Toutefois, vous pouvez utiliser la slicers propriété pour modifier l’état des segments existants, comme le montre le code suivant :

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

Pour plus d’informations sur la modification de l’état d’un segment, consultez Contrôler les segments de rapport .

Signet à la charge

À l’aide de la bookmark propriété , vous pouvez appliquer un signet à un rapport incorporé. Pour plus d’informations sur l’utilisation de signets pour capturer l’affichage actuellement configuré des pages de rapport, consultez Signets .

Vous pouvez spécifier le signet à utiliser en fournissant le nom du signet ou l’état. Si vous fournissez le nom du signet, votre rapport Power BI doit contenir un signet enregistré portant ce nom.

La bookmark propriété est de type IApplyBookmarkRequest. Le code suivant montre la définition de ce type :

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Ce code montre comment spécifier un signet par nom :

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

Ce code montre comment spécifier un signet par état :

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

Thèmes et mode contraste élevé

Vous pouvez contrôler le thème et le niveau de contraste que votre contenu incorporé utilise. Par défaut, tout contenu que vous incorporez apparaît avec le thème par défaut et avec un contraste nul. Vous pouvez remplacer ce comportement en configurant un thème ou un niveau de contraste spécifique. Pour plus d’informations sur les thèmes, consultez Appliquer des thèmes de rapport.

Les modes de contraste disponibles sont répertoriés ci-dessous :

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

Utilisez un code similaire aux lignes suivantes pour configurer un thème spécifique :

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

Le code suivant montre comment remplacer le niveau de contraste par défaut : None

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

Notes

L’API ne peut pas appliquer un thème et un niveau de contraste en même temps. Si vous configurez les deux propriétés, l’API utilise le niveau de contraste que vous avez spécifié, mais ignore le theme paramètre.

Niveau de zoom

Pour en savoir plus sur l’ajustement du niveau de zoom du rapport case activée le document d’accessibilité.

Ouvrir en mode Édition

Par défaut, le rapport que vous incorporez s’affiche en mode affichage. Toutefois, vous pouvez remplacer ce comportement pour ouvrir le rapport en mode édition. Vous pouvez également basculer entre les modes.

Configurer le mode d’édition

Pour ouvrir un rapport incorporé en mode édition, utilisez la viewMode propriété avec la permissions propriété .

Vous pouvez affecter à la viewMode propriété les valeurs suivantes :

  • View - Ouvre le rapport en mode Affichage.
  • Edit - Ouvre le rapport en mode édition.

Vous pouvez affecter à la permissions propriété les valeurs suivantes :

  • Read - Les utilisateurs peuvent afficher le rapport.
  • ReadWrite - Les utilisateurs peuvent afficher, modifier et enregistrer le rapport.
  • Copy - Les utilisateurs peuvent enregistrer une copie du rapport à l’aide de Enregistrer sous.
  • Create - Les utilisateurs peuvent créer un rapport.
  • All - Les utilisateurs peuvent créer, afficher, modifier, enregistrer et enregistrer une copie du rapport.

Lorsque vous configurez le contenu pour qu’il s’ouvre en mode édition, attribuez à la permissions propriété une valeur appropriée pour la modification, comme le montre le code suivant :

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

Notes

La permissions valeur que vous configurez ne fonctionne que si le jeton incorporé que vous avez acquis dispose de privilèges suffisants. Pour plus d’informations sur les jetons incorporés, consultez Créer le jeton incorporé.

Basculer entre les modes d’édition et d’affichage

En plus de spécifier un mode de démarrage du contenu incorporé, vous pouvez également basculer dynamiquement entre les modes d’édition et d’affichage.

Si le contenu est en mode édition et que vous souhaitez passer en mode affichage, utilisez ce code JavaScript :

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

...

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

Si le contenu est en mode affichage et que vous souhaitez passer en mode édition, utilisez ce code JavaScript :

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

...

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

Considérations et limitations

Tenez compte des points suivants lorsque vous configurez du contenu incorporé :

  • La position de navigation de la page ne peut pas être modifiée lorsque la barre d’action est visible. En savoir plus sur la barre d’action.

  • Lorsque vous utilisez la bars propriété dans la setting propriété, comme décrit dans Barres, l’API applique votre configuration uniquement si le contenu incorporé est en mode édition. Si votre contenu est en mode affichage, l’API ignore le bars paramètre.

  • Lorsque vous utilisez la propriété pour afficher du viewMode contenu en mode édition, vous devez effectuer deux étapes supplémentaires :

    • Configurez un niveau d’autorisation avec la permissions propriété . Ce niveau d’autorisation doit donner à l’utilisateur l’accès approprié pour modifier le contenu. Par instance, si vous affectez une permissions valeur de l’utilisateur Read, ne pourra pas modifier le contenu.
    • Vérifiez que le jeton incorporé que vous générez dispose de privilèges qui prennent en charge la modification. Par instance, si vous obtenez un jeton avec une accessLevel valeur de l’APIview,, le contenu n’est pas affiché en mode édition.

  • La propriété panes remplace les propriétés suivantes settings :

    • filterPaneEnabled
    • navContentPaneEnabled

    Si vous utilisez la propriété pour configurer la panes visibilité du filtre ou de la navigation dans les pages, n’utilisez pas la filterPaneEnabled propriété ou navContentPaneEnabled dans votre application.

  • L’API ne peut pas appliquer un thème et un niveau de contraste au contenu incorporé en même temps. Si vous configurez les deux options à l’aide des theme propriétés et contrastMode , l’API utilise votre contrastMode valeur avec le contenu incorporé. Toutefois, l’API ignore le theme paramètre.

  • Si vous souhaitez appliquer un signet à un rapport incorporé, vous pouvez utiliser la bookmark propriété . Si vous fournissez un nom de signet avec cette propriété, l’API ne peut utiliser le signet que s’il existe avec ce nom. De même, si vous utilisez la pageName propriété pour spécifier une page d’ouverture, l’API ne peut afficher cette page que si elle existe avec le nom donné. Avant de configurer un nom, envisagez d’utiliser une méthode d’accesseur, telle que la méthode getPages de rapport, pour case activée si un composant existe avec ce nom.

Étapes suivantes