嵌入式分析 SDK - 仪表板

嵌入式分析 SDK 仅适用于 ProEnterprise 计划(包括自托管和 Metabase 云版)。但是,您可以通过使用 API 密钥验证嵌入来在本地机器上无需许可证即可试用 SDK。

您可以嵌入交互式、可编辑或静态仪表板。

请注意 - 同一页面上嵌入多个仪表板实例尚不受支持。

嵌入仪表板

您可以使用其中一个仪表板组件嵌入仪表板

StaticDashboard

一个轻量级的仪表板组件。当您只想显示结果而不允许用户与数据交互时,请使用此组件。

API 参考

属性

属性 类型 描述
className? 字符串 要添加到根元素的自定义类名。
dashboardId SdkDashboardId 仪表板的 ID。
这可以是
- 访问仪表板链接时的数字 ID,例如 http://localhost:3000/dashboard/1-my-dashboard,其中 ID 为 1
- 使用 API 直接访问或使用 SDK 集合浏览器返回数据时,仪表板对象的 entity_id 键中找到的字符串 ID
hiddenParameters? 字符串[] 隐藏的参数列表。
- 结合 initialParametershiddenParameters 在前端过滤数据存在安全风险
- 结合 initialParametershiddenParameters 以简化用户界面是可以的。
initialParameters? ParameterValues 仪表板的查询参数。对于单个选项,使用 string 值;对于多个选项,使用字符串列表。
- 结合 initialParametershiddenParameters 在前端过滤数据存在安全风险
- 结合 initialParametershiddenParameters 以简化用户界面是可以的。
onLoad? (dashboard: null | MetabaseDashboard) => void 仪表板加载时调用的回调。
onLoadWithoutCards? (dashboard: null | MetabaseDashboard) => void 仪表板在没有卡片的情况下加载时调用的回调。
style? CSSProperties 要添加到根元素的自定义样式对象。
withCardTitle? 布尔值 仪表板卡片是否应显示标题。
withDownloads? 布尔值 是否隐藏下载按钮。
withTitle? 布尔值 仪表板是否应显示标题。

InteractiveDashboard

一个具有钻取、点击行为以及查看和点击问题能力的仪表板组件。当您希望允许用户探索他们的数据时,请使用此组件。

API 参考

属性

属性 类型 描述
className? 字符串 要添加到根元素的自定义类名。
dashboardId SdkDashboardId 仪表板的 ID。
这可以是
- 访问仪表板链接时的数字 ID,例如 http://localhost:3000/dashboard/1-my-dashboard,其中 ID 为 1
- 使用 API 直接访问或使用 SDK 集合浏览器返回数据时,仪表板对象的 entity_id 键中找到的字符串 ID
drillThroughQuestionHeight? Height<string | number> 从仪表板钻取到问题级别时,问题组件的高度。
drillThroughQuestionProps? DrillThroughQuestionProps 从仪表板钻取到问题级别时,问题组件的属性。
hiddenParameters? 字符串[] 隐藏的参数列表。
- 结合 initialParametershiddenParameters 在前端过滤数据存在安全风险
- 结合 initialParametershiddenParameters 以简化用户界面是可以的。
initialParameters? ParameterValues 仪表板的查询参数。对于单个选项,使用 string 值;对于多个选项,使用字符串列表。
- 结合 initialParametershiddenParameters 在前端过滤数据存在安全风险
- 结合 initialParametershiddenParameters 以简化用户界面是可以的。
onLoad? (dashboard: null | MetabaseDashboard) => void 仪表板加载时调用的回调。
onLoadWithoutCards? (dashboard: null | MetabaseDashboard) => void 仪表板在没有卡片的情况下加载时调用的回调。
plugins? MetabasePluginsConfig 覆盖或添加钻取菜单的额外映射函数。有关更多详细信息,请参阅实现自定义操作部分。
renderDrillThroughQuestion? () => ReactNode 用于渲染问题布局的自定义 React 组件。使用命名空间 InteractiveQuestion 组件来构建布局。
style? CSSProperties 要添加到根元素的自定义样式对象。
withCardTitle? 布尔值 仪表板卡片是否应显示标题。
withDownloads? 布尔值 是否隐藏下载按钮。
withTitle? 布尔值 仪表板是否应显示标题。

EditableDashboard

一个仪表板组件,具有 InteractiveDashboard 组件中可用的功能,以及在仪表板中添加和更新问题、布局和内容的能力。当您希望用户能够修改您的仪表板时,例如在您的应用管理面板中,请使用此组件。

API 参考

属性

属性 类型 描述
className? 字符串 要添加到根元素的自定义类名。
dashboardId SdkDashboardId 仪表板的 ID。
这可以是
- 访问仪表板链接时的数字 ID,例如 http://localhost:3000/dashboard/1-my-dashboard,其中 ID 为 1
- 使用 API 直接访问或使用 SDK 集合浏览器返回数据时,仪表板对象的 entity_id 键中找到的字符串 ID
drillThroughQuestionHeight? 数字 从仪表板钻取到问题级别时,问题组件的高度。
drillThroughQuestionProps? DrillThroughQuestionProps 钻取问题的属性
initialParameters? ParameterValues 仪表板的查询参数。对于单个选项,使用 string 值;对于多个选项,使用字符串列表。
- 结合 initialParametershiddenParameters 在前端过滤数据存在安全风险
- 结合 initialParametershiddenParameters 以简化用户界面是可以的。
onLoad? (dashboard: null | MetabaseDashboard) => void 仪表板加载时调用的回调。
onLoadWithoutCards? (dashboard: null | MetabaseDashboard) => void 仪表板在没有卡片的情况下加载时调用的回调。
plugins? MetabasePluginsConfig 覆盖或添加钻取菜单的额外映射函数。有关更多详细信息,请参阅实现自定义操作部分。
style? CSSProperties 要添加到根元素的自定义样式对象。
withCardTitle? 布尔值 仪表板卡片是否应显示标题。
withDownloads? 布尔值 是否隐藏下载按钮。

带有 InteractiveDashboard 组件的嵌入式仪表板示例

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

const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://your-metabase.example.com",
});

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={hiddenParameters}
      />
    </MetabaseProvider>
  );
}

自定义仪表板高度

默认情况下,仪表板组件占据整个页面高度(100vh)。您可以通过 styleclassName 属性传递自定义样式来覆盖此设置。

<EditableDashboard
  style={{
    height: 800,
    minHeight: "auto",
  }}
  dashboardId={dashboardId}
/>

自定义钻取问题布局

当您钻取或点击仪表板中的问题卡片时,您将被带到问题视图。默认情况下,问题会以交互式问题的默认布局显示。

要自定义问题布局,请将 renderDrillThroughQuestion 属性传递给 InteractiveDashboard 组件,并将自定义视图作为子组件。

<InteractiveDashboard
  dashboardId={95}
  renderDrillThroughQuestion={QuestionView}
/>

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

questionView 属性接受一个 React 组件,该组件将在问题视图中渲染,您可以使用 InteractiveQuestion 组件中的命名空间组件来构建它。有关示例布局,请参阅自定义交互式问题

仪表板插件

dashboardCardMenu

此插件允许您添加、删除和修改仪表板卡片溢出菜单上的自定义操作。该插件以下拉菜单的形式出现在卡片的右上角。

该插件的默认配置如下所示

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

dashboardCardMenu: 可以在 InteractiveDashboard 中这样使用

<InteractiveDashboard
  dashboardId={1}
  plugins={{
    dashboard: {
      dashboardCardMenu: () => null,
    },
  }}
/>

启用/禁用默认操作

要从仪表板卡片菜单中移除下载按钮,请将 withDownloads 设置为 false。要从仪表板卡片菜单中移除编辑链接,请将 withEditLink 设置为 false

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

向现有菜单添加自定义操作

您可以通过向 customItems 数组添加对象来向仪表板卡片菜单添加自定义操作。每个元素可以是一个对象,也可以是一个接受仪表板卡片问题并输出自定义项目列表的函数,形式如下:

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

这是一个示例

const plugins: MetabasePluginsConfig = {
  dashboard: {
    dashboardCardMenu: {
      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: {
    dashboardCardMenu: ({ question }) => (
      <button onClick={() => console.log(question.name)}>Click me</button>
    ),
  },
};

创建仪表板

可以使用 useCreateDashboardApi hook 或 CreateDashboardModal 组件创建仪表板。

useCreateDashboardApi

如果您想完全控制 UI 和设置,请使用此 hook。

API 参考

示例

const { createDashboard } = useCreateDashboardApi();

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

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

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

选项

属性 类型 描述
collectionId SdkCollectionId 创建新仪表板的集合。您可以使用预定义的系统值,例如 rootpersonal
description null | string 仪表板描述
name 字符串 仪表板标题

CreateDashboardModal

API 参考

示例

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

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

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

属性

属性 类型 描述
initialCollectionId? SdkCollectionId 创建仪表板的初始集合。您可以使用预定义的系统值,例如 rootpersonal
isOpen? 布尔值 模态框是否打开。
onClose? () => void 关闭模态组件的处理器
onCreate (dashboard: MetabaseDashboard) => void 仪表板创建时的响应处理器。

阅读其他 Metabase 版本的文档。

© . All rights reserved.