定價
登入 開始使用
文件 學習
首頁
分析
嵌入
管理
其他資源

嵌入式分析 SDK - 儀表板

⚠️ 此功能為測試版。歡迎隨意試用，但請注意，內容可能會變更 (且可能無法如預期般運作)。

嵌入式分析 SDK 僅適用於 Pro 和 Enterprise 方案 (包括自架主機和 Metabase Cloud)。但是，您可以使用 API 金鑰驗證您的嵌入，在沒有授權的情況下，在本機電腦上試用 SDK。

您可以嵌入互動式、可編輯或靜態儀表板。

請記住，目前尚不支援在同一頁面上嵌入多個儀表板執行個體。

嵌入儀表板

您可以使用其中一個儀表板元件嵌入儀表板

  • InteractiveDashboard
  • StaticDashboard
  • EditableDashboard

儀表板元件屬性

屬性 類型 描述
dashboardId number \| string 儀表板的 ID。可以是
- 存取儀表板連結時的數字 ID，例如 https://127.0.0.1:3000/dashboard/1-my-dashboard，其中的 ID 為 1
- 使用 API 直接或使用 SDK 集合瀏覽器傳回資料時，在儀表板物件的 entity_id 金鑰中找到的字串 ID
initialParameters** Record<string, string \| string[]> 儀表板的查詢參數。對於單一選項，請使用 string 值，對於多個選項，請使用字串清單。
withTitle boolean 儀表板是否應顯示標題。
withCardTitle boolean 儀表板卡片是否應顯示標題。
withDownloads boolean \| null 是否隱藏下載按鈕。
hiddenParameters** string[] \| null 要隱藏的參數清單。
drillThroughQuestionHeight* number \| null 從儀表板向下鑽研至問題層級時，問題元件的高度。
questionPlugins* { mapQuestionClickActions: Function } \| null 用於覆寫或新增向下鑽研選單的其他對應器函式。請參閱實作自訂動作章節以取得更多詳細資訊。
onLoad (dashboard: Dashboard \| null) => void 儀表板載入所有可見卡片及其內容後觸發的事件處理常式。
onLoadWithoutCards (dashboard: Dashboard \| null) => void 儀表板載入後觸發的事件處理常式，但不包含其卡片 - 在此階段，儀表板標題、索引標籤和卡片網格會呈現，但卡片內容尚未載入。
renderDrillThroughQuestion* () => ReactNode 一個 React 元件，用於呈現問題的版面配置，此版面配置會在向下鑽研問題或按一下儀表板中的問題卡片後顯示。

* 不適用於 StaticDashboard。

** 結合 initialParameters 和 hiddenParameters 在前端篩選資料是一種安全性風險。結合 initialParameters 和 hiddenParaters 來整理使用者介面是可行的。

依預設，儀表板元件會佔用整個頁面高度 (100vh)。您可以使用透過 style 或 className 屬性傳遞的自訂樣式來覆寫此設定。

<EditableDashboard
  style=
  dashboardId={dashboardId}
/>

具有 InteractiveDashboard 元件的嵌入式儀表板範例

import React from "react";
import {MetabaseProvider, InteractiveDashboard} from "@metabase/embedding-sdk-react";

const authConfig = {...}

export default function App() {
    const dashboardId = 1; // This is the dashboard ID you want to embed
    const initialParameters = {}; // Define your query parameters here

    // choose parameter names that are in your dashboard
    const hiddenParameters = ["location", "city"]

    return (
        <MetabaseProvider authConfig={authConfig}>
            <InteractiveDashboard
                dashboardId={dashboardId}
                initialParameters={initialParameters}
                withTitle={false}
                withDownloads={false}
                hiddenParameters={hideParameters}
            />
        </MetabaseProvider>
    );
}

自訂向下鑽研問題版面配置

當向下鑽研或按一下儀表板中的問題卡片時，您將會進入問題檢視畫面。

依預設，問題會顯示在互動式問題的預設版面配置中。

若要自訂問題版面配置，請將 renderDrillThroughQuestion 屬性傳遞至 InteractiveDashboard 元件，並以自訂檢視畫面作為子元件。

<InteractiveQuestion
  questionId={95}
  renderDrillThroughQuestion={QuestionView}
/>;

// You can use namespaced components to build the question's layout.
const QuestionView = () => <InteractiveQuestion.Title />;

questionView 屬性接受一個 React 元件，該元件將會在問題檢視畫面中呈現，您可以使用 InteractiveQuestion 元件中的命名空間元件來建置該元件。請參閱自訂互動式問題以取得版面配置範例。

儀表板外掛程式

dashcardMenu

此外掛程式可讓您在儀表板卡片的溢位選單上新增、移除和修改自訂動作。此外掛程式會以下拉式選單的形式顯示在卡片的右上角。

此外掛程式的預設組態如下

const plugins = {
  dashboard: {
    dashcardMenu: {
      withDownloads: true,
      withEditLink: true,
      customItems: [],
    },
  },
};

dashcardMenu：可以在 InteractiveDashboard 中像這樣使用


<InteractiveDashboard
  questionId={1}
  plugins={{
    dashboard: {
      dashcardMenu: null,
    },
  }}
/>

啟用/停用預設動作

若要從 dashcard 選單中移除下載按鈕，請將 withDownloads 設定為 false。若要從 dashcard 選單中移除編輯連結，請將 withEditLink 設定為 false。

const plugins = {
  dashboard: {
    dashcardMenu: {
      withDownloads: false,
      withEditLink: false,
      customItems: [],
    },
  },
};

將自訂動作新增至現有選單

您可以將物件新增至 customItems 陣列，將自訂動作新增至 dashcard 選單。每個元素可以是物件或函式，此函式會接收 dashcard 的問題，並以如下形式輸出自訂項目清單

{
    iconName: string;
    label: string;
    onClick: () => void;
    disabled?: boolean;
}

以下範例

const plugins: MetabasePluginsConfig = {
  dashboard: {
    dashcardMenu: {
      customItems: [
        {
          iconName: "chevronright",
          label: "Custom action",
          onClick: () => {
            alert(`Custom action clicked`);
          },
        },
        ({ question }) => {
          return {
            iconName: "chevronright",
            label: "Custom action",
            onClick: () => {
              alert(`Custom action clicked ${question.name}`);
            },
          };
        },
      ],
    },
  },
};

將現有選單取代為您自己的元件

如果您想要將現有選單取代為您自己的元件，您可以透過提供傳回 React 元件的函式來執行此動作。此函式也可以接收問題作為引數。

const plugins: MetabasePluginsConfig = {
  dashboard: {
    dashcardMenu: ({ question }) => (
      <button onClick={() => console.log(question.name)}>Click me</button>
    ),
  },
};

建立儀表板

可以使用 useCreateDashboardApi Hook 或 CreateDashboardModal 元件來建立儀表板。

Hook

const { createDashboard } = useCreateDashboardApi();

const handleDashboardCreate = async () => {
  const dashboard = await createDashboard(props);

  // do something with created empty dashboard, e.g., use the dashboard in EditableDashboard component
};

return <Button onClick={handleDashboardCreate}>Create new dashboard</Button>;

屬性

屬性 類型 描述
name string (必要) 儀表板標題
description string \| null 選用儀表板描述
collectionId number \| 'root' \| 'personal' \| null 要在其中建立新儀表板的集合。您可以使用預先定義的系統值，例如 root 或 personal。

元件

const [dashboard, setDashboard] = useState<Dashboard | null>(null);

if (dashboard) {
  return <EditableDashboard dashboardId={dashboard.id} />;
}

return <CreateDashboardModal onClose={handleClose} onCreate={setDashboard} />;

支援的元件屬性

屬性 類型 描述
collectionId? number \| 'root' \| 'personal' \| null 初始集合欄位值。您可以使用預先定義的系統值，例如 root 或 personal。
onCreate (dashboard: Dashboard) => void 用於對儀表板建立做出反應的處理常式。
onClose () => void 用於關閉強制回應元件的處理常式

閱讀其他版本的 Metabase 文件。