嵌入式分析 SDK - 仪表板

嵌入式分析 SDK 仅适用于 ProEnterprise 计划(包括自托管和 Metabase 云服务)。但是,您可以在本地机器上通过使用 API 密钥进行嵌入式身份验证,在没有许可证的情况下试用 SDK。

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

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

嵌入仪表板

您可以使用仪表板组件之一嵌入仪表板

StaticDashboard(静态仪表板)

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

API参考

属性

属性 类型 描述
className? 字符串 要添加到根元素的自定义类名。
dashboardId SdkDashboardId 仪表板的 ID。
这可以是
- 访问仪表板链接时的数字 ID,即 https://:3000/dashboard/1-my-dashboard,其中 ID 是 1
- 使用 API 直接访问或使用 SDK Collection Browser 返回数据时,仪表板对象 entity_id 键中的字符串 ID
dataPickerProps? Pick<SdkQuestionProps, "entityTypes"> 创建新的仪表板问题时,要传递给 InteractiveQuestion 渲染的查询构建器的附加属性。
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? 布尔值 仪表板是否显示标题。

InteractiveDashboard(交互式仪表板)

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

API参考

属性

属性 类型 描述
className? 字符串 要添加到根元素的自定义类名。
dashboardId SdkDashboardId 仪表板的 ID。
这可以是
- 访问仪表板链接时的数字 ID,即 https://:3000/dashboard/1-my-dashboard,其中 ID 是 1
- 使用 API 直接访问或使用 SDK Collection Browser 返回数据时,仪表板对象 entity_id 键中的字符串 ID
dataPickerProps? Pick<SdkQuestionProps, "entityTypes"> 创建新的仪表板问题时,要传递给 InteractiveQuestion 渲染的查询构建器的附加属性。
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,即 https://:3000/dashboard/1-my-dashboard,其中 ID 是 1
- 使用 API 直接访问或使用 SDK Collection Browser 返回数据时,仪表板对象 entity_id 键中的字符串 ID
dataPickerProps? Pick<SdkQuestionProps, "entityTypes"> 创建新的仪表板问题时,要传递给 InteractiveQuestion 渲染的查询构建器的附加属性。
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? 布尔值 仪表板是否显示标题。

使用 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 的文档。

这有帮助吗?

感谢您的反馈!
想改进这些文档吗?建议修改。
© . This site is unofficial and not affiliated with Metabase, Inc.