自訂 QuickSight 內嵌儀表板和視覺效果的外觀和風格 - Amazon QuickSight
術語與概念設定SDK 方法介面使用主題初始化內嵌內容使用主題覆寫初始化內嵌內容使用預先載入的主題初始化內嵌內容

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

自訂 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。您可以選擇現有的主題，也可以建立新的主題。若要取得ARNs QuickSight 帳戶中所有主題的清單，請呼叫 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);