Configurer les paramètres de rapport

À l’aide des API clientes Power BI, vous pouvez incorporer l’analytique Power BI 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.

Outre l’accès de l’API au rapport, vous pouvez également utiliser l’objet de configuration pour personnaliser l’apparence et le comportement de votre rapport. Par exemple, vous pouvez ajuster la visibilité du filtre, l’accès à la navigation et les paramètres 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 clientes Power BI sur 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;
}

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

Personnaliser les paramètres

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

Vitres

Contrôlez l’apparence de tous les volets de votre rapport Power BI avec une propriété panes unique, 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 quelles valeurs chaque propriété panes prend en charge :

Volet Filtre

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

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

Volet de navigation de page

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

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

Le volet de navigation de page apparaît en bas du rapport pour utiliser le nouveau volet de pages verticales que vous pouvez définir la propriété position :

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

Bars

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

Barre d’actions

Le code suivant rend la barre d’action visible :

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

Sinon, en mode affichage, il est également possible d’utiliser le paramètre d’URL actionBarEnabled :

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

Barre d’état

La barre d’état contient le contrôleur de zoom de canevas, qui permet de zoomer sur le canevas.

Le code suivant rend la barre d’état visible :

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

Paramètres régionaux

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

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

• langue définit la langue utilisée par Power BI pour la localisation. Voici quelques exemples de langues : en (anglais), es (espagnol) et tr (turc).
• paramètres régionaux définit la mise en forme de texte utilisée par Power BI pour les dates, la devise et d’autres contenus connexes. Parmi les paramètres régionaux, citons (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 des valeurs spécifiques à ces localeSettings:

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

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 que vous souhaitez à l’élément HTML div qui contient le contenu incorporé. Le style de l’élément div devient alors visible.

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

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

Comportement du clic sur un lien hypertexte

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.

Modes de comportement disponibles :

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

• Navigate : l’URL est chargée dans un nouveau contexte de navigation.
• NavigateAndRaiseEvent : l’URL est chargée dans un nouveau contexte de navigation et déclenche un événement dataHyperlinkClicked.
• RaiseEvent : empêche le comportement par défaut du clic d’URL et déclenche dataHyperlinkClicked événement.

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

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

Un événement dataHyperlinkClicked se déclenche lorsqu’un lien hypertexte est cliqué sur une table ou des visuels matrices prêtes à l’emploi et que le comportement est NavigateAndRaiseEvent ou RaiseEvent.

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 événements visualRendered :

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

Un événement visualRendered 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.

Messages d’erreur

Si vous souhaitez afficher des messages d’erreur personnalisés dans des rapports incorporés, utilisez la propriété hideErrors 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 qui correspond à la conception de votre application. Consultez remplacer les messages d’erreur par défaut pour plus d’informations sur la substitution d’erreurs 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 davantage de propriétés 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 propriété pageName 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 chargement

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 d’autres filtres à utiliser avec les filtres enregistrés. Le code suivant montre comment utiliser la propriété filters pour ajouter d’autres filtres :

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

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

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 propriété slicers 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.

Sur le signet de chargement

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

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 propriété bookmark 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.

Modes de contraste disponibles :

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

Pour configurer un thème spécifique, utilisez du code similaire aux lignes suivantes :

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

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

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

Niveau de zoom

Pour en savoir plus sur l’ajustement du niveau de zoom du rapport, vérifiez le document d’accessibilité .

Ouvrir en mode édition

Par défaut, le rapport que vous incorporez apparaît 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 propriété viewMode avec la propriété permissions.

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

• View : ouvre le rapport en mode affichage.
• Edit : ouvre le rapport en mode édition.

Vous pouvez affecter la propriété permissions 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 à ouvrir en mode édition, affectez à la propriété permissions une valeur appropriée pour la modification, comme le montre le code suivant :

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

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

Outre la spécification d’un mode pour le contenu incorporé à démarrer, vous pouvez également basculer entre les modes d’édition et d’affichage dynamiquement.

Si le contenu est en mode édition et que vous souhaitez basculer vers le mode d’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 navigation page position ne peut pas être modifiée lorsque la barre d’action est visible. En savoir plus sur la barre d’actions .

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

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

  • Configurez un niveau d’autorisation avec la propriété permissions. Ce niveau d’autorisation doit donner à l’utilisateur l’accès approprié pour modifier le contenu. Par exemple, si vous affectez une valeur permissions de Read, l’utilisateur 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 exemple, si vous obtenez un jeton avec une valeur accessLevel de view, l’API ne parvient pas à afficher le contenu en mode édition.

• La propriété volets remplace les propriétés de settings suivantes :

  • filterPaneEnabled
  • navContentPaneEnabled

  Si vous utilisez la propriété panes pour configurer la visibilité du filtre ou de la navigation de page, n’utilisez pas la propriété filterPaneEnabled 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 propriétés theme et contrastMode, l’API utilise votre valeur contrastMode avec le contenu incorporé. Toutefois, l’API ignore le paramètre theme.

• Si vous souhaitez appliquer un signet à un rapport incorporé, vous pouvez utiliser la propriété bookmark. 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 propriété pageName 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 Report getPages, pour vérifier si un composant existe avec ce nom.

Contenu connexe

• Améliorer l’expérience de vos utilisateurs avec les signets
• Appliquer des thèmes de rapport dans Power BI
• filtres de rapport Control
• Contrôler les segments de rapport