Personnalisez l'apparence des tableaux de bord et des visuels QuickSight intégrés

Vous pouvez utiliser le SDK Amazon QuickSight Embedding (version 2.5.0 et ultérieure) pour modifier le thème de vos QuickSight tableaux de bord et visuels intégrés lors de l'exécution. La thématisation du runtime facilite l'intégration de votre application SaaS (Software as a Service) à vos actifs QuickSight intégrés Amazon. Le thème d'exécution vous permet de synchroniser le thème de votre contenu intégré avec les thèmes de l'application parent dans laquelle vos QuickSight actifs sont intégrés. Vous pouvez également utiliser les thèmes d'exécution pour ajouter des options de personnalisation pour les lecteurs. Les modifications de thème peuvent être appliquées aux ressources intégrées lors de l'initialisation ou pendant toute la durée de vie de votre tableau de bord ou visuel intégré.

Pour plus d'informations sur les thèmes, consultezUtilisation de thèmes sur Amazon QuickSight. Pour plus d'informations sur l'utilisation du SDK d' QuickSight intégration, consultez le amazon-quicksight-embedding-sdk GitHub

Prérequis

Avant de commencer, assurez-vous que vous remplissez les conditions préalables suivantes.

• Vous utilisez le SDK QuickSight d'intégration version 2.5.0 ou supérieure.

• Autorisations pour accéder au thème avec lequel vous souhaitez travailler. Pour accorder des autorisations à un thème dans QuickSight, effectuez un appel d'UpdateThemePermissionsAPI ou utilisez l'icône Partager située à côté du thème dans l'éditeur d'analyse de la QuickSight console.

Terminologie et concepts

La terminologie suivante peut être utile lorsque vous travaillez avec des thèmes d'exécution intégrés.

• Thème : ensemble de paramètres que vous pouvez appliquer à plusieurs analyses et tableaux de bord qui modifient la façon dont le contenu est affiché.

• ThemeConfiguration— Objet de configuration contenant toutes les propriétés d'affichage d'un thème.

• Remplacer le thème : ThemeConfiguration objet appliqué au thème actif pour remplacer certains ou tous les aspects de la façon dont le contenu est affiché.

• ARN du thème : nom de ressource Amazon (ARN) identifiant un QuickSight thème. Voici un exemple d'ARN de thème personnalisé.

  arn:aws:quicksight:region:account-id:theme/theme-id

  QuickSight les thèmes de démarrage fournis n'ont pas de région dans leur ARN de thème. Voici un exemple d'ARN de thème de démarrage.

  arn:aws:quicksight::aws:theme/CLASSIC

Configuration

Assurez-vous d'avoir les informations suivantes à portée de main pour commencer à travailler avec les thèmes d'exécution.

• Thème ARNs des thèmes que vous souhaitez utiliser. Vous pouvez choisir un thème existant ou en créer un nouveau. Pour obtenir une liste de tous ARNs les thèmes et thèmes de votre QuickSight compte, appelez l'opération ListThemesAPI. Pour plus d'informations sur les QuickSight thèmes prédéfinis, consultezDéfinition d'un thème par défaut pour QuickSight les analyses Amazon avec QuickSight APIs.

• Si vous utilisez l'intégration d'utilisateurs enregistrés, assurez-vous que l'utilisateur a accès aux thèmes que vous souhaitez utiliser.

  Si vous utilisez l'intégration d'utilisateurs anonymes, transmettez une liste de thèmes ARNs au AuthorizedResourceArns paramètre de l'GenerateEmbedUrlForAnonymousUserAPI. Les utilisateurs anonymes ont accès à n'importe quel thème répertorié dans le AuthorizedResourceArns paramètre.

Interface de la méthode SDK

Méthodes Setter

Le tableau suivant décrit les différentes méthodes de réglage que les développeurs peuvent utiliser pour la thématisation de l'exécution.

Méthode	Description
setTheme(themeArn: string)	Remplace le thème actif d'un tableau de bord ou d'un visuel par un autre thème. S'il est appliqué, le remplacement du thème est supprimé. Une erreur est renvoyée si vous n'avez pas accès au thème ou si le thème n'existe pas.
setThemeOverride(themeOverride: ThemeConfiguration)	Définit une dynamique ThemeConfiguration pour remplacer le thème actif actuel. Cela remplace le remplacement du thème défini précédemment. Toutes les valeurs qui ne sont pas fournies dans le nouveau thème ThemeConfiguration sont par défaut celles du thème actuellement actif. Une erreur est renvoyée si le message ThemeConfiguration que vous avez fourni n'est pas valide.

Initialisation du contenu intégré avec un thème

Pour initialiser un tableau de bord ou un visuel intégré avec un thème autre que celui par défaut, définissez un themeOptions objet sur les VisualContentOptions paramètres DashboardContentOptions or, puis définissez la themeArn propriété sur l'themeOptionsARN du thème souhaité.

L'exemple suivant initialise un tableau de bord intégré avec le MIDNIGHT thème.

import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        themeArn: "arn:aws:quicksight::aws:theme/MIDNIGHT"
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);

Initialisation du contenu intégré avec un remplacement de thème

Les développeurs peuvent utiliser des remplacements de thème pour définir le thème d'un tableau de bord intégré ou d'un visuel lors de l'exécution. Cela permet au tableau de bord ou au visuel d'hériter d'un thème d'une application tierce sans qu'il soit nécessaire de préconfigurer un thème intégré. QuickSight Pour initialiser un tableau de bord ou un visuel intégré avec un remplacement de thème, définissez la themeOverride propriété themeOptions dans les paramètres DashboardContentOptions ouVisualContentOptions. L'exemple suivant remplace la police du thème d'un tableau de bord par la police par défaut par. Amazon Ember

import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        "themeOverride":{"Typography":{"FontFamilies":[{"FontFamily":"Comic Neue"}]}}
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);

Initialisation du contenu intégré avec des thèmes préchargés

Les développeurs peuvent configurer un ensemble de thèmes de tableau de bord à précharger lors de l'initialisation. Cela est particulièrement utile pour passer rapidement d'une vue à l'autre, par exemple en mode sombre et en mode clair. Un tableau de bord ou un visuel intégré peut être initialisé avec jusqu'à 5 thèmes préchargés. Pour utiliser des thèmes préchargés, définissez la preloadThemes propriété dans un tableau allant jusqu'à 5 DashboardContentOptions themeArns ou VisualContentOptions dans un tableau. L'exemple suivant précharge les thèmes Midnight et Rainier Starter dans un tableau de bord.

import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        "preloadThemes": ["arn:aws:quicksight::aws:theme/RAINIER", "arn:aws:quicksight::aws:theme/MIDNIGHT"]
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);