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

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

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

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

如需有關主題圖的更多資訊，請參閱在 Amazon 中使用主題 QuickSight。有關如何使用「 QuickSight 嵌入」的更多內容SDK，敬請參閱（詳見） GitHub。amazon-quicksight-embedding-sdk

先決條件

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

  • 您使用的是 QuickSight 嵌入SDK版本 2.5.0 或更高版本。

  • 存取您要使用之佈景主題的權限。若要授與中佈景主題的權限 QuickSight，請撥UpdateThemePermissionsAPI打電話或使用主 QuickSight 控台分析編輯器中該佈景主題旁邊的「分享」圖示。

術語與概念

使用嵌入式執行階段主題設定時，下列術語非常有用。

  • 主題 — 可套用至多個分析和儀表板的設定集合，這些分析和儀表板會變更內容的顯示方式。

  • ThemeConfiguration— 包含主題所有顯示屬性的配置物件。

  • 佈景主題覆寫 — 套用至作用中佈景主題的ThemeConfiguration物件，以覆寫內容顯示方式的部分或所有層面。

  • 主題 ARN — 標識主 QuickSight 題的 Amazon 資源名稱 (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 分析設置默認主題。

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

    如果您使用匿名使用者內嵌，請將主題清單傳遞ARNs給的AuthorizedResourceArns參數GenerateEmbedUrlForAnonymousUserAPI。匿名使用者可以存取AuthorizedResourceArns參數中列出的任何佈景主題。

SDK方法介面

二傳手方法

下表說明開發人員可以用於執行階段主題化的不同 setter 方法。

方法 描述

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其中預先配置主題。若要使用主題取代來初始化內嵌儀表板或視覺效果，請themeOptions在DashboardContentOptions或VisualContentOptions參數中設定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 個預加載的主題進行初始化。若要使用預先載入的主題，請將preloadThemes屬性設定為DashboardContentOptions或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);