自訂 QuickSight 內嵌儀表板和視覺效果的外觀和風格

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

如需主題的詳細資訊，請參閱 在 Amazon 中使用主題 QuickSight。如需使用 QuickSight 內嵌 的詳細資訊SDK，請參閱 amazon-quicksight-embedding-sdk上的 GitHub。

先決條件

在開始之前，請確定您具備下列先決條件。

• 您正在使用 QuickSight 內嵌 2SDK.5.0 版或更新版本。

• 存取您要使用之主題的許可。若要在 中授予主題許可 QuickSight，UpdateThemePermissionsAPI請呼叫 或使用 QuickSight 主控台分析編輯器中主題旁的共用圖示。

術語與概念

下列術語在處理內嵌執行時間時非常有用。

• 佈景主題 – 一組設定，您可以套用到多個分析和儀表板，以變更內容的顯示方式。

• ThemeConfiguration – 包含佈景主題所有顯示屬性的組態物件。

• 主題覆寫 – 套用至作用中主題的ThemeConfiguration物件，可覆寫內容顯示方式的部分或全部層面。

• 主題 ARN – 識別主題的 Amazon Resource Name QuickSight (ARN)。以下是自訂主題 的範例ARN。

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

  QuickSight 提供的入門主題在其主題 中沒有 區域ARN。以下是入門主題 的範例ARN。

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

設定

請確定您已備妥下列資訊，可以開始使用執行時間。

• 您想要使用ARNs的主題。您可以選擇現有的佈景主題，也可以建立新的佈景主題。若要取得 QuickSight 您帳戶中所有主題ARNs的清單，請呼叫 ListThemesAPI操作。如需預設 QuickSight 主題的詳細資訊，請參閱 使用 設定 Amazon QuickSight 分析的預設主題 QuickSight APIs。

• 如果您使用的是已註冊的使用者內嵌，請確定使用者可存取您要使用的主題。

  如果您使用匿名使用者內嵌，請將主題清單傳遞ARNs至 GenerateEmbedUrlForAnonymousUser 的 AuthorizedResourceArns 參數API。匿名使用者有權存取 AuthorizedResourceArns 參數中列出的任何主題。

SDK 方法界面

設定程式方法

下表說明開發人員可用於執行時間的不同設定程式方法。

方法	描述
setTheme(themeArn: string)	將儀表板或視覺效果的作用中主題取代為另一個主題。如果套用，則會移除主題覆寫。 如果您無法存取主題或主題不存在，則會傳回錯誤。
setThemeOverride(themeOverride: ThemeConfiguration)	設定動態ThemeConfiguration以覆寫目前的作用中主題。這會取代先前設定的主題覆寫。任何未在新 中提供的值ThemeConfiguration，都會預設為目前作用中主題中的值。 如果您提供的 無效ThemeConfiguration，則會傳回錯誤。

使用佈景主題初始化內嵌內容

若要使用非預設佈景主題初始化內嵌儀表板或視覺效果，請在 DashboardContentOptions或 VisualContentOptions 參數上定義themeOptions物件，並將 中的 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 個預先載入的主題進行初始化。若要使用預先載入的主題，請在 DashboardContentOptions或 中設定 preloadThemes 屬性VisualContentOptions，陣列最多為 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);