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

# 自定义 Amazon Quick Sight 嵌入式仪表板和视觉效果的外观
<a name="embedding-runtime-theming"></a>

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

有关主题的更多信息，请参阅 [使用 Amazon Quick Sight 中的主题](themes-in-quicksight.md)。有关使用 Amazon Quick Sight 嵌入软件开发工具包的更多信息，请参阅[amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)上的 GitHub。

**先决条件**

在开始之前，请确保您已满足以下先决条件。
+ 你使用的是 Amazon Quick Sight Embedding SDK 版本 2.5.0 或更高版本
+ 访问您想要使用的主题的权限。要在 Amazon Quick Sight 中授予主题的权限，请调用 `UpdateThemePermissions` API 或使用 Amazon Quick Sight 控制台分析编辑器中主题旁边的**共享**图标。

## 术语和概念
<a name="runtime-theming-terminology"></a>

使用嵌入式运行时主题时，以下术语可能很有用。
+ *主题* – 可应用于多个分析和控制面板的设置集合，可更改内容的显示方式。
+ *ThemeConfiguration*— 包含主题所有显示属性的配置对象。
+ *主题覆盖* - 应用于活动主题的 `ThemeConfiguration` 对象，用于覆盖内容显示方式的部分或全部方面。
+ *主题 ARN* — 标识亚马逊 Quick Sight 主题的亚马逊资源名称 (ARN)。以下是自定义主题 ARN 的示例。

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

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

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

## 设置
<a name="runtime-theming-setup"></a>

确保您已准备好以下信息，以开始使用运行时主题。
+ 您要使用的主题的主题。 ARNs 您可以选择现有主题，也可以创建一个新主题。要获取您的 Amazon Quick Sight 账户 ARNs 中所有主题和主题的列表，请调用 [ListThemes](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_ListThemes.html)API 操作。有关预设 Amazon Quick Sight 主题的信息，请参阅[使用 Amazon Quick 为 Amazon Quick 分析设置默认主题 APIs](customizing-quicksight-default-theme.md)。
+ 如果您使用注册用户嵌入，请确保该用户可以访问您想要使用的主题。

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

## SDK 方法接口
<a name="runtime-theming-sdk-interface"></a>

**Setter 方法**

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


| 方法 | 说明 | 
| --- | --- | 
|  `setTheme(themeArn: string)`  |  将控制面板或视觉对象的活动主题替换为其他主题。如果应用，则会移除主题覆盖。 如果您无权访问主题或主题不存在，则会返回错误。  | 
|  `setThemeOverride(themeOverride: ThemeConfiguration)`  |  设置动态 `ThemeConfiguration` 以覆盖当前活动主题。这将替换之前设置的主题覆盖。新 `ThemeConfiguration` 中未提供的任何值都将默认为当前活动主题中的值。 如果您提供的 `ThemeConfiguration` 无效，则会返回错误。  | 

## 使用主题初始化嵌入式内容
<a name="runtime-theming-sdk-initialize"></a>

要使用非默认主题初始化嵌入式控制面板或视觉对象，请在 `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);
```

## 使用主题覆盖初始化嵌入式内容
<a name="runtime-theming-runtime-initialize-override"></a>

开发人员可以使用主题覆盖在运行时定义嵌入式控制面板或视觉对象的主题。这允许控制面板或视觉对象从第三方应用程序继承主题，而无需在 Amazon Quick Sight 中预先配置主题。要使用主题覆盖初始化嵌入式控制面板或视觉对象，请在 `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);
```

## 使用预加载的主题初始化嵌入式内容
<a name="runtime-theming-runtime-initialize-preloaded"></a>

开发人员可以配置一组控制面板主题，以便在初始化时预加载。这对于在不同视图（例如深色和浅色模式）之间快速切换最为有利。嵌入式控制面板或视觉对象最多可使用 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);
```