嵌入式分析SDK - 仪表板
嵌入式分析 SDK 仅在 Pro 和 Enterprise 计划(包括自托管和 Metabase Cloud)中可用。
您可以嵌入一个交互式、可编辑或静态的仪表板。
请注意,目前不支持在同一页面上嵌入多个仪表板实例。
嵌入仪表板
您可以使用以下仪表板组件之一来嵌入仪表板:
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 渲染的其他属性。 |
hiddenParameters? |
字符串[] |
要隐藏的参数列表。 - 组合使用initialParameters和hiddenParameters在前端过滤数据是有安全风险的。 - 组合使用initialParameters和hiddenParameters来简化用户界面是可以的。 |
initialParameters? |
ParameterValues |
仪表板的查询参数。对于单个选项,使用string值,对于多个选项,使用字符串列表。- 组合使用initialParameters和hiddenParameters在前端过滤数据是有安全风险的。 - 组合使用initialParameters和hiddenParameters来简化用户界面是可以的。 |
onLoad? |
(dashboard: null | MetabaseDashboard) => void |
仪表板加载时调用的回调函数。 |
onLoadWithoutCards? |
(dashboard: null | MetabaseDashboard) => void |
仪表板在没有卡片的情况下加载时调用的回调函数。 |
onVisualizationChange? |
(visualization: | "object" | "table" | "bar" | "line" | "pie" | "scalar" | "row" | "area" | "combo" | "pivot" | "smartscalar" | "gauge" | "progress" | "funnel" | "map" | "scatter" | "waterfall" | "sankey" | "list") => void |
当从仪表板卡片打开问题或用户更改问题的可视化类型时触发的回调函数。 |
plugins? |
MetabasePluginsConfig |
用于覆盖或添加钻取菜单的附加映射函数。详情请参见实现自定义操作部分。 |
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 |
仪表板在没有卡片的情况下加载时调用的回调函数。 |
onVisualizationChange? |
(visualization: | "object" | "table" | "bar" | "line" | "pie" | "scalar" | "row" | "area" | "combo" | "pivot" | "smartscalar" | "gauge" | "progress" | "funnel" | "map" | "scatter" | "waterfall" | "sankey" | "list") => 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 |
仪表板在没有卡片的情况下加载时调用的回调函数。 |
onVisualizationChange? |
(visualization: | "object" | "table" | "bar" | "line" | "pie" | "scalar" | "row" | "area" | "combo" | "pivot" | "smartscalar" | "gauge" | "progress" | "funnel" | "map" | "scatter" | "waterfall" | "sankey" | "list") => 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>
),
},
};
mapQuestionClickActions
您可以使用mapQuestionClickActions插件来自定义当用户点击仪表板上的数据点时会发生什么。请参阅mapQuestionClickActions。
创建仪表板
可以通过useCreateDashboardApi hook或CreateDashboardModal组件来创建仪表板。
useCreateDashboardApi
如果您希望完全控制UI和设置,请使用此hook。
在嵌入式分析SDK完全加载并初始化之前,hook返回null。
API参考
示例
const hookResult = useCreateDashboardApi();
const handleDashboardCreate = async () => {
// hookResult is `null` until the SDK is fully loaded and initialized
if (!hookResult) {
return;
}
const dashboard = await hookResult.createDashboard(options);
// do something with created empty dashboard, e.g., use the dashboard in EditableDashboard component
};
return <button onClick={handleDashboardCreate}>Create new dashboard</button>;
Options
| 属性 | 类型 | 描述 |
|---|---|---|
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 的文档。