自定义 QuickSight 嵌入式控制面板和视觉对象的外观 - Amazon QuickSight
术语和概念设置SDK 方法接口使用主题初始化嵌入式内容使用主题覆盖初始化嵌入式内容使用预加载的主题初始化嵌入式内容
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

自定义 QuickSight 嵌入式控制面板和视觉对象的外观

您可以使用 Amazon QuickSight Embedding SDK（版本 2.5.0 及更高版本）在运行时更改嵌入式 QuickSight 控制面板和视觉对象的主题。运行时主题使您能够更轻松地将软件即服务（SaaS）应用程序与 Amazon QuickSight 嵌入式资产集成。运行时主题允许您将嵌入式内容的主题与 QuickSight 资产嵌入的父应用程序的主题同步。您还可以使用运行时主题为读者添加自定义选项。主题更改可以在初始化时应用于嵌入式资产，也可以在嵌入式控制面板或视觉对象的整个生命周期内应用。

有关主题的更多信息，请参阅 在 Amazon QuickSight 中使用主题。有关使用 QuickSight Embedding SDK 的更多信息，请参阅 GitHub 上的 amazon-quicksight-embedding-sdk。

先决条件

在开始之前，请确保您已满足以下先决条件。

  • 您正在使用 QuickSight Embedding SDK 版本 2.5.0 或更高版本。

  • 访问您想要使用的主题的权限。要授予对 QuickSight 中主题的权限，请进行 UpdateThemePermissions API 调用或使用 QuickSight 控制台分析编辑器中主题旁边的共享图标。

术语和概念

使用嵌入式运行时主题时，以下术语可能很有用。

  • 主题 – 可应用于多个分析和控制面板的设置集合，可更改内容的显示方式。

  • ThemeConfiguration – 包含主题的所有显示属性的配置对象。

  • 主题覆盖 - 应用于活动主题的 ThemeConfiguration 对象，用于覆盖内容显示方式的部分或全部方面。

  • 主题 ARN – 用于标识 QuickSight 主题的 Amazon 资源名称（ARN）。以下是自定义主题 ARN 的示例。

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

    QuickSight 提供的入门主题在其主题 ARN 中没有区域。以下是入门主题 ARN 的示例。

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

设置

确保您已准备好以下信息，以开始使用运行时主题。

  • 您想要使用的主题的主题 ARN。您可以选择现有主题，也可以创建一个新主题。要获取 QuickSight 账户中的所有主题和主题 ARN 列表，请调用 ListThemes API 操作。有关预设 QuickSight 主题的信息，请参阅 使用 QuickSight API 为 Amazon QuickSight 分析设置默认主题。

  • 如果您使用注册用户嵌入，请确保该用户可以访问您想要使用的主题。

    如果您使用匿名用户嵌入，请将主题 ARN 列表传递给 GenerateEmbedUrlForAnonymousUser API 的 AuthorizedResourceArns 参数。匿名用户有权访问 AuthorizedResourceArns 参数中列出的任何主题。

SDK 方法接口

Setter 方法

下表介绍了开发人员可以用于运行时主题的不同 setter 方法。

方法 描述

setTheme(themeArn: string)

将控制面板或视觉对象的活动主题替换为其他主题。如果应用，则会移除主题覆盖。

如果您无权访问主题或主题不存在，则会返回错误。

setThemeOverride(themeOverride: ThemeConfiguration)

设置动态 ThemeConfiguration 以覆盖当前活动主题。这将替换之前设置的主题覆盖。新 ThemeConfiguration 中未提供的任何值都将默认为当前活动主题中的值。

如果您提供的 ThemeConfiguration 无效，则会返回错误。

使用主题初始化嵌入式内容

要使用非默认主题初始化嵌入式控制面板或视觉对象，请在 DashboardContentOptions 或 VisualContentOptions 参数上定义 themeOptions 对象，并将 themeOptions 中的 themeArn 属性设置为所需的主题 ARN。

以下示例使用 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);

使用主题覆盖初始化嵌入式内容

开发人员可以使用主题覆盖在运行时定义嵌入式控制面板或视觉对象的主题。这样，控制面板或视觉对象就可以从第三方应用程序继承主题，而无需在 QuickSight 中预先配置主题。要使用主题覆盖初始化嵌入式控制面板或视觉对象，请在 DashboardContentOptions 或 VisualContentOptions 参数中的 themeOptions 中设置 themeOverride 属性。以下示例将控制面板主题的字体从默认字体覆盖为 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);

使用预加载的主题初始化嵌入式内容

开发人员可以配置一组控制面板主题，以便在初始化时预加载。这对于在不同视图（例如深色和浅色模式）之间快速切换最为有利。嵌入式控制面板或视觉对象最多可使用 5 个预加载的主题进行初始化。要使用预加载的主题，请使用最多 5 个 themeArns 的数组在 DashboardContentOptions 或 VisualContentOptions 中设置 preloadThemes 属性。以下示例将 Midnight 和 Rainier 入门主题预加载到控制面板。

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