定价
登录 开始使用
文档 学习
首页
分析
嵌入
管理
其他资源

嵌入式分析 SDK - 仪表盘

⚠️ 此功能为 Beta 版。欢迎试用，但请注意，功能可能会发生变化（并且可能无法按预期工作）。

嵌入式分析 SDK 仅在 Pro 和 Enterprise 计划（自托管和 Metabase 云）中提供。但是，您可以在本地机器上使用 SDK，无需许可证，只需使用 API 密钥来验证您的嵌入。

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

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

嵌入仪表盘

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

  • 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,
    },
  }}
/>

启用/禁用默认操作

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

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

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

您可以通过向 customItems 数组添加对象来向仪表盘卡片菜单添加自定义操作。每个元素可以是对象或函数，该函数接收仪表盘卡片的问题，并以以下形式输出自定义项列表

{
    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 其他版本的文档。