本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 自訂 Amazon Quick Sight 內嵌儀表板和視覺效果的外觀和風格
<a name="embedding-runtime-theming"></a>

您可以使用 Amazon Quick Sight 內嵌 SDK (2.5.0 版及更高版本），在執行時間變更內嵌 Amazon Quick Sight 儀表板和視覺效果。執行時間它們可讓您更輕鬆地將軟體即服務 (SaaS) 應用程式與 Amazon Quick Sight 內嵌資產整合。執行期它們可讓您將內嵌內容的主題與內嵌 Amazon Quick Sight 資產的父應用程式主題同步。您也可以使用執行時期佈景主題設定，為讀者新增自訂選項。佈景主題設定變更可在初始化時或嵌入式儀表板或視覺效果的整個生命週期內套用至嵌入式資產。

如需有關佈景主題的詳細資訊，請參閱[在 Amazon Quick Sight 中使用佈景主題](themes-in-quicksight.md)。如需使用 Amazon Quick Sight 內嵌 SDK 的詳細資訊，請參閱 GitHub 上的 [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)。

**先決條件**

開始使用之前，請確定已滿足下列必要先決條件。
+ 您使用的是 Amazon Quick Sight 內嵌 SDK 2.5.0 版或更新版本。
+ 要使用之佈景主題的存取許可。若要在 Amazon Quick Sight 中授予佈景主題的許可，請進行 `UpdateThemePermissions` API 呼叫或使用 Amazon Quick Sight 主控台分析編輯器中佈景主題旁的**共用**圖示。

## 術語與概念
<a name="runtime-theming-terminology"></a>

下列術語在使用嵌入執行時期佈景主題設定時非常實用。
+ *佈景主題*：您可以套用到多個分析和儀表板，以變更內容顯示方式的一組設定。
+ *佈景主題組態*：包含佈景主題所有顯示屬性的組態物件。
+ *佈景主題覆寫*：套用至作用中佈景主題的 `ThemeConfiguration` 物件，可覆寫內容顯示方式的部分或全部層面。
+ *佈景主題 ARN * – 識別 Amazon Quick Sight 佈景主題的 Amazon Resource Name (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>

請確定您已準備好下列資訊，以開始使用執行時期佈景主題設定。
+ 想要使用之佈景主題的 ARN。您可以選擇現有的佈景主題，也可以建立新的佈景主題。若要取得 Amazon Quick Sight 帳戶中所有佈景主題和佈景主題 ARNs清單，請呼叫 [ListThemes](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_ListThemes.html) API 操作。如需預設 Amazon Quick Sight 主題的詳細資訊，請參閱 [使用 Amazon Quick APIs 設定 Amazon Quick 分析的預設佈景主題](customizing-quicksight-default-theme.md)。
+ 如果您使用的是已註冊的使用者嵌入，請確定使用者可存取您想要使用的佈景主題。

  如果您使用匿名使用者嵌入，請將佈景主題 ARN 清單傳遞至 `GenerateEmbedUrlForAnonymousUser` API 的 `AuthorizedResourceArns` 參數。匿名使用者可存取 `AuthorizedResourceArns` 參數中列出的任何佈景主題。

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

**Setter 方法**

下表說明開發人員可用於執行時期佈景主題設定的不同 Setter 方法。


| Method | Description | 
| --- | --- | 
| `setTheme(themeArn: string)` | 以另一個佈景主題取代儀表板或視覺效果的作用中佈景主題。如果套用，則會移除佈景主題覆寫。<br />如果您無法存取佈景主題或佈景主題不存在，則會傳回錯誤。 | 
| `setThemeOverride(themeOverride: ThemeConfiguration)` | 設定動態 `ThemeConfiguration` 以覆寫目前的作用中佈景主題。這會取代先前設定的佈景主題覆寫。任何未在新 `ThemeConfiguration` 中提供的值，都會預設為目前作用中佈景主題中的值。<br />如果您提供的 `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 個預先載入佈景主題。若要使用預先載入佈景主題，請在 `DashboardContentOptions` 或 `VisualContentOptions` 中設定 `preloadThemes` 屬性，陣列最多可達 5 個 `themeArns`。下列範例會將 `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);
```