嵌入式分析 SDK - 仪表板
嵌入式分析 SDK 仅适用于 Pro 和 Enterprise 计划(包括自托管和 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? |
字符串 [] |
要隐藏的参数列表。 - 结合 initialParameters 和 hiddenParameters 在前端过滤数据存在安全风险。 - 结合 initialParameters 和 hiddenParameters 以简化用户界面是可以的。 |
initialParameters? |
ParameterValues |
仪表板的查询参数。对于单个选项,使用 string 值;对于多个选项,使用字符串列表。- 结合 initialParameters 和 hiddenParameters 在前端过滤数据存在安全风险。 - 结合 initialParameters 和 hiddenParameters 以简化用户界面是可以的。 |
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? |
字符串 [] |
要隐藏的参数列表。 - 结合 initialParameters 和 hiddenParameters 在前端过滤数据存在安全风险。 - 结合 initialParameters 和 hiddenParameters 以简化用户界面是可以的。 |
initialParameters? |
ParameterValues |
仪表板的查询参数。对于单个选项,使用 string 值;对于多个选项,使用字符串列表。- 结合 initialParameters 和 hiddenParameters 在前端过滤数据存在安全风险。 - 结合 initialParameters 和 hiddenParameters 以简化用户界面是可以的。 |
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 值;对于多个选项,使用字符串列表。- 结合 initialParameters 和 hiddenParameters 在前端过滤数据存在安全风险。 - 结合 initialParameters 和 hiddenParameters 以简化用户界面是可以的。 |
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)。您可以通过 style
或 className
属性传递自定义样式来覆盖此设置。
<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 |
创建新仪表板的集合。您可以使用预定义的系统值,例如 root 或 personal 。 |
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 |
创建仪表板的初始集合。您可以使用预定义的系统值,例如 root 或 personal 。 |
isOpen? |
布尔值 |
模态框是否打开。 |
onClose? |
() => void |
关闭模态组件的处理器 |
onCreate |
(dashboard : MetabaseDashboard ) => void |
仪表板创建时的响应处理器。 |
阅读其他 Metabase 版本的文档。