自定义嵌入式仪表板和视觉对象的外观 - Amazon QuickSight
术语和概念设置SDK 方法接口使用主题初始化嵌入式内容使用主题覆盖初始化嵌入式内容使用预加载的主题初始化嵌入式内容

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

自定义嵌入式仪表板和视觉对象的外观

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

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

先决条件

在开始之前，请确保您具备以下先决条件。

  • 您使用的是 Embedg QuickSight ing SDK 版本 2.5.0 或更高版本。

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

术语和概念

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

  • 主题-一组设置，您可以将其应用于多个分析和仪表板，用于更改内容的显示方式。

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

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

  • 主题 ARN — 标识主题的亚马逊资源名称 (ARN)。 QuickSight 以下是自定义主题 ARN 的示例。

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

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

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

设置

请务必准备好以下信息，以便开始使用运行时主题。

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

  • 如果您使用的是注册用户嵌入，请确保用户有权访问您要使用的主题。

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

SDK 方法接口

设置器方法

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

方法 描述

setTheme(themeArn: string)

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

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

setThemeOverride(themeOverride: ThemeConfiguration)

设置动态ThemeConfiguration以覆盖当前活动主题。这将取代先前设置的主题覆盖。新版本中未提供的任何值ThemeConfiguration都默认为当前活动主题中的值。

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

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

要使用非默认主题初始化嵌入式仪表板或视觉themeOptions对象，请在DashboardContentOptions或VisualContentOptions参数上定义对象，然后将中的themeArn属性设置themeOptions为所需的主题 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 的数组将preloadThemes属性设置为其中一个DashboardContentOptions或VisualContentOptions。以下示例将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);