Personalização da aparência dos painéis e dos elementos visuais incorporados do QuickSight - Amazon QuickSight
Terminologia e conceitosConfiguraçãoInterface para métodos do SDKInicialização de conteúdo incorporado com um temaInicialização de conteúdo incorporado com uma substituição de temaInicialização de conteúdo incorporado com temas carregados previamente

Personalização da aparência dos painéis e dos elementos visuais incorporados do QuickSight

É possível usar o SDK de incorporação do Amazon QuickSight (versão 2.5.0 e versões superiores) para fazer alterações no tema dos painéis e elementos visuais incorporados do QuickSight durante o runtime. O tema do runtime facilita a integração da aplicação de software como serviço (SaaS) com os ativos incorporados do Amazon QuickSight. O tema do runtime permite que você sincronize o tema do conteúdo incorporado com os temas da aplicação principal na qual os ativos do QuickSight estão incorporados. Além disso, é possível usar o tema do runtime para adicionar opções de personalização para leitores. As alterações de tema podem ser aplicadas a ativos incorporados na inicialização ou durante toda a vida útil do painel ou do elemento visual incorporado.

Para obter mais informações sobre os temas, consulte Como usar temas no Amazon QuickSight. Para obter mais informações sobre como usar o SDK de incorporação do QuickSight, consulte amazon-quicksight-embedding-sdk no GitHub.

Pré-requisitos

Antes de começar a usar, certifique-se de cumprir os pré-requisitos apresentados a seguir.

  • Você deve estar usando o SDK de incorporação do QuickSight na versão 2.5.0 ou em versões superiores.

  • Você deve ter permissões para acessar o tema com o qual deseja trabalhar. Para conceder permissões a um tema no QuickSight, faça uma chamada de API UpdateThemePermissions ou use o ícone Compartilhar ao lado do tema no editor de análises do console do QuickSight.

Terminologia e conceitos

A terminologia apresentada a seguir pode ser útil ao trabalhar com temas de runtime incorporados.

  • Tema: uma coleção de configurações que você pode aplicar a várias análises e painéis que alteram a forma como o conteúdo é exibido.

  • ThemeConfiguration: esta configuração contém todas as propriedades de exibição para um tema.

  • Substituição de tema: um objeto ThemeConfiguration que é aplicado ao tema ativo para substituir alguns ou todos os aspectos de como o conteúdo é exibido.

  • ARN do tema: um nome do recurso da Amazon (ARN) que identifica um tema do QuickSight. A seguir, apresentamos um exemplo de ARN para um tema personalizado.

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

    Os temas padrão fornecidos pelo QuickSight não têm uma região em seu ARN do tema. A seguir, apresentamos um exemplo de um ARN para um tema padrão.

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

Configuração

Certifique-se de ter as informações apresentadas a seguir disponíveis para começar a trabalhar com temas de runtime.

  • Os ARNs dos temas dos temas que você deseja usar. É possível escolher um tema existente ou criar um novo. Para obter uma lista de todos os temas e ARNs dos temas na sua conta do QuickSight, faça uma chamada para a operação ListThemes da API. Para obter informações sobre os temas definidos previamente do QuickSight, consulte Definição de um tema padrão para análises do Amazon QuickSight com as APIs do QuickSight.

  • Se você estiver usando a incorporação para usuários registrados, certifique-se de que o usuário tenha acesso aos temas que deseja usar.

    Se você estiver usando a incorporação para usuários anônimos, forneça uma lista de ARNs dos temas para o parâmetro AuthorizedResourceArns da API GenerateEmbedUrlForAnonymousUser. Os usuários anônimos terão acesso a qualquer tema que esteja listado no parâmetro AuthorizedResourceArns.

Interface para métodos do SDK

Métodos “setter”

A tabela apresentada a seguir descreve diferentes métodos “setter” que os desenvolvedores podem usar para os temas de runtime.

Método Descrição

setTheme(themeArn: string)

Substitui o tema ativo de um painel ou de um elemento visual por outro tema. Se aplicado, a substituição do tema será removida.

Um erro será retornado se você não tiver acesso ao tema ou se o tema não existir.

setThemeOverride(themeOverride: ThemeConfiguration)

Define uma ThemeConfiguration dinâmica para substituir o tema ativo atual. Isso substitui a substituição do tema definida anteriormente. Quaisquer valores que não são fornecidos na nova ThemeConfiguration serão padronizados para os valores do tema ativo no momento.

Um erro será retornado se a ThemeConfiguration fornecida for inválida.

Inicialização de conteúdo incorporado com um tema

Para inicializar um painel ou um elemento visual incorporado com um tema que não corresponde ao padrão, defina um objeto themeOptions nos parâmetros DashboardContentOptions ou VisualContentOptions, e configure a propriedade themeArn em themeOptions com o ARN do tema desejado.

O exemplo apresentado a seguir inicializa um painel incorporado com o tema MIDNIGHT.

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

Inicialização de conteúdo incorporado com uma substituição de tema

Os desenvolvedores podem usar substituições de tema para definir o tema de um painel ou de um elemento visual incorporado durante o runtime. Isso permite que o painel ou o elemento visual herde um tema de uma aplicação proveniente de entidades externas, sem a necessidade de configurar um tema previamente no QuickSight. Para inicializar um painel ou um elemento visual incorporado com uma substituição de tema, defina a propriedade themeOverride em themeOptions nos parâmetros DashboardContentOptions ou VisualContentOptions. O exemplo apresentado a seguir substitui a fonte do tema de um painel, alterando da fonte padrão para 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);

Inicialização de conteúdo incorporado com temas carregados previamente

Os desenvolvedores podem configurar um conjunto de temas de painel para serem carregados previamente na inicialização. Isso é especialmente útil para alternar rapidamente entre diferentes modos de visualização, como os modos escuro e claro. Um painel ou um elemento visual incorporado pode ser inicializado com até cinco temas carregados previamente. Para usar temas carregados previamente, defina a propriedade preloadThemes em DashboardContentOptions ou em VisualContentOptions com uma matriz que contém até cinco themeArns. O exemplo apresentado a seguir carrega previamente os temas padrão Midnight e Rainier para um painel.

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