嵌入式分析 SDK - 仪表板
嵌入式分析 SDK 仅适用于 Pro 和 Enterprise 计划(包括自托管和 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? |
字符串 [] |
要隐藏的参数列表。 - 结合 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? |
布尔值 |
仪表板是否显示标题。 |
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? |
字符串 [] |
要隐藏的参数列表。 - 结合 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,即 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? |
字符串 [] |
要隐藏的参数列表。 - 结合 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? |
布尔值 |
仪表板是否显示标题。 |
使用 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 的文档。