Metabase Embedding SDK 实战指南EditableDashboard 可编辑仪表盘组件【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase导读EditableDashboard是 Metabase Embedding SDK 提供的可编辑仪表盘组件它在InteractiveDashboard支持钻取、点击行为、查看问题的全部能力之上额外允许最终用户在嵌入应用中添加、更新问题question、调整布局与内容。本文将以 EditableDashboard.md 为核心完整讲解其函数签名、EditableDashboardProps全部参数语义并结合仓库源码剖析其可编辑能力的底层实现与受控参数机制帮助你正确选用仪表盘组件并把可编辑能力安全、可控地嵌入到自己的产品中。组件定位三种仪表盘组件的能力分层在 Metabase Embedding SDK 中仪表盘Dashboard组件族分为三档能力层级从 API 索引 的 Dashboard 分组可以清晰看到它们的定位组件定位StaticDashboard轻量级只读仪表盘组件InteractiveDashboard支持钻取、点击行为、可查看并点击进入问题的仪表盘EditableDashboard具备InteractiveDashboard全部特性且可添加/更新问题、布局与内容从源码 EditableDashboard.tsx 可以看到EditableDashboard并不是从零实现而是基于通用底座SdkDashboard定制而来export type EditableDashboardProps SdkDashboardProps EditableDashboardOwnProps; export const EditableDashboard Object.assign( withPublicComponentWrapper(EditableDashboardInner, { supportsGuestEmbed: false, // 可编辑仪表盘不支持游客嵌入 }), { schema: editableDashboardSchema, }, );其中supportsGuestEmbed: false是一个关键事实可编辑仪表盘不支持匿名游客guest嵌入模式因为编辑仪表盘必然涉及写操作需要真实的已认证用户身份。函数签名与返回类型原文档给出组件签名如下function EditableDashboard(props: EditableDashboardProps): Element;参数唯一的入参是props其完整类型为EditableDashboardProps。返回值一个 ReactElement即渲染后的嵌入组件节点。组件自身的静态schema除了作为组件渲染外EditableDashboard还通过Object.assign挂载了一个静态schema属性见 EditableDashboard.schema.ts它基于 Yup 定义了可接受 props 的白名单结构const propsSchema: Yup.SchemaOfEditableDashboardProps Yup.object({ children: Yup.mixed().optional(), className: Yup.mixed().optional(), dashboardId: Yup.mixed().required(), // 唯一必填项 token: Yup.mixed().optional(), dataPickerProps: Yup.object({ entityTypes: Yup.mixed().optional() }) .optional() .noUnknown(), // 拒绝 schema 未声明的字段 // ... drillThroughQuestionProps、hiddenParameters、initialParameters、 // parameters、onParametersChange、onLoad、onLoadWithoutCards、 // plugins、renderDrillThroughQuestion、style、autoRefreshInterval、 // withCardTitle、withDownloads、withSubscriptions、withTitle、 // onVisualizationChange、enableEntityNavigation }).noUnknown();从 schema 结构可以推断dashboardId是唯一必填属性且.noUnknown()校验策略意味着传入未声明字段会被拒绝——这对于确保嵌入参数可预测、避免误传是重要的约束。EditableDashboardProps 完整参数详解EditableDashboardProps.md 定义了组件的全部可配置项。下面按功能域分组展开标?为可选属性。基础标识与样式属性类型说明dashboardIdstring \| number必填。仪表盘 ID二选一数字 ID访问链接如http://localhost:3000/dashboard/1-my-dashboard中的1或通过 API / SDK Collection Browser 拿到的entity_id字符串。底层类型别名见 SdkDashboardIdnumber \| string \| SdkEntityIdtoken?string \| null覆盖默认的嵌入令牌原文档未展开说明schema 中声明为可选className?string追加到根元素的自定义类名style?CSSProperties追加到根元素的自定义样式对象仪表盘渲染控制属性类型说明withTitle?boolean是否显示仪表盘标题withCardTitle?boolean是否显示卡片card标题withDownloads?boolean是否隐藏下载按钮withSubscriptions?boolean是否显示订阅按钮autoRefreshInterval?number仪表盘自动刷新间隔单位为秒enableEntityNavigation?boolean为true时保留内部点击行为跳转仪表盘/问题链接为falseSDK 默认值时过滤掉这些点击行为这些展示控制项在源码中直接参与组件挂载埋点见 EditableDashboard.tsxuseTrackSdkComponentMount(EditableDashboard, dashboardId, { with_title: withTitle, with_downloads: withDownloads, with_subscriptions: withSubscriptions, auto_refresh: autoRefreshInterval ! null, enable_entity_navigation: enableEntityNavigation, });参数Parameters相关SDK 对仪表盘参数filter的支持分为一次性初始值与受控值两种模式均以 slug 作为键initialParameters?— 类型ParameterValues。挂载时一次性应用的初始参数值用户之后在控件上的编辑不会回传宿主。每个参数的取值规则设为值单选为字符串、多选为字符串数组应用该值设为null严格清空忽略参数自身默认值省略或设为undefined回退到参数默认值无默认值则为null。parameters?— 类型ParameterValues。受控参数值每次渲染时用该对象整体替换仪表盘参数值。规则与initialParameters一致但它是持续受控的——应配合onParametersChange同步用户编辑形成单向数据流 回传的闭环。hiddenParameters?—string[]。需要隐藏的参数列表。安全提示原文档明确警告用initialParameters/parameters组合hiddenParameters在前端过滤数据属于安全风险每个终端用户都必须有自己的 Metabase 账号不应这样用仅用于整理界面如隐藏不想展示的过滤控件则没有问题。onParametersChange?—(payload: ParameterChangePayload) void。参数变化回调payload 的source字段区分三类事件见 ParameterChangePayload 与 index.md 中的 ParameterChangeSourceinitial-state加载时首次应用快照每次仪表盘加载触发一次manual-change用户在 UI 中编辑参数auto-change自动更新场景例如把归一化后的值回传给父组件。payload 结构{ defaultParameters, lastUsedParameters, parameters, source }其中parameters为当前生效值defaultParameters为默认值lastUsedParameters为最近一次使用的值。生命周期回调属性类型说明onLoad?(dashboard: MetabaseDashboard \| null) void仪表盘加载完成后回调onLoadWithoutCards?(dashboard: MetabaseDashboard \| null) void仪表盘无卡片加载完成时回调onVisualizationChange?(visualization: ... ) void从仪表盘卡片打开问题或用户更换问题可视化类型时触发类型为 21 种可视化名称的联合object \| table \| bar \| line \| pie \| scalar \| row \| area \| combo \| pivot \| smartscalar \| gauge \| progress \| funnel \| map \| scatter \| boxplot \| waterfall \| sankey \| treemap \| listonLoad回调收到的dashboard对象是 MetabaseDashboard 实体包含id、entity_id、name、description、collection、created_at、updated_at以及last-edit-infoemail、first_name、last_name、id、timestamp等字段——其中last-edit-info对可编辑仪表盘场景尤其有用可用于展示上次由谁编辑的信息。钻取Drill-through与插件扩展属性类型说明drillThroughQuestionHeight?Heightstring \| number从仪表盘钻取到问题层级时问题组件的高度drillThroughQuestionProps?DrillThroughQuestionProps钻取到问题层级时问题组件的 props其plugins字段会被用于构造点击行为模式见下方源码renderDrillThroughQuestion?() ReactNode自定义问题布局的 React 组件应使用带命名空间的InteractiveQuestion组件来构建布局plugins?MetabasePluginsConfig用于覆盖或新增钻取菜单的 mapper 函数详见实现自定义 actions相关章节在源码 EditableDashboard.tsx 中钻取行为被显式装配为SDK 嵌入模式const clickActionMode useMemo( () getEmbeddingMode({ queryMode: createEmbeddingSdkMode({ pushNavigation }), plugins: props.drillThroughQuestionProps?.plugins, }), [pushNavigation, props.drillThroughQuestionProps?.plugins], );新建问题时的数据选择器dataPickerProps?—PickSdkQuestionProps, entityTypes。透传给新建仪表盘问题时由InteractiveQuestion渲染的查询构建器query builder的附加 props目前只开放entityTypes限制可选择的数据实体类型。schema 中也仅放行dataPickerProps.entityTypes单个字段。源码视角可编辑是如何实现的编辑态与非编辑态的头部动作EditableDashboard与InteractiveDashboard最本质的差异体现在 dashboardActions 工厂函数const dashboardActions: SdkDashboardInnerProps[dashboardActions] ({ isEditing, }) isEditing ? DASHBOARD_EDITING_ACTIONS : [ DASHBOARD_ACTION.EDIT_DASHBOARD, DASHBOARD_ACTION.DASHBOARD_SUBSCRIPTIONS, DASHBOARD_ACTION.DOWNLOAD_PDF, DASHBOARD_ACTION.REFRESH_INDICATOR, ];非编辑态提供编辑仪表盘入口EDIT_DASHBOARD、订阅DASHBOARD_SUBSCRIPTIONS、导出 PDFDOWNLOAD_PDF与刷新指示器REFRESH_INDICATOR编辑态isEditing为真切换为完整的仪表盘编辑动作集合DASHBOARD_EDITING_ACTIONS常量定义见 constants.ts这就是添加/更新问题、调整布局与内容能力的 UI 入口。内嵌导航与受控参数内嵌导航EditableDashboardInner使用SdkInternalNavigationProvider包裹内容见 EditableDashboard.tsx为仪表盘内部跳转提供pushNavigation上下文受控参数底层SdkDashboard见 SdkDashboard.tsx通过useSdkControlledParameters等 hooks 处理parameters/initialParameters的合并语义并有useWarnConflictingParameterProps对相互冲突的参数 props 给出告警getEffectiveParameterValues负责计算最终生效的参数值。这也解释了原文档中initialParameters与parameters两种模式的差异。最小使用示例组件需要先由 MetabaseProvider 提供认证与主题上下文之后即可在任意页面级组件中渲染import { EditableDashboard, MetabaseProvider } from metabase/embedding-sdk-react; export function AdminDashboard() { return ( MetabaseProvider authConfig{{ metabaseInstanceUrl: https://metabase.example.com, ... }} EditableDashboard dashboardIdmY-dAsHbOaRd-eNtItY withTitle{true} withCardTitle{true} withDownloads{false} enableEntityNavigation{false} initialParameters{{ region: APAC }} onLoad{(dashboard) console.log(loaded:, dashboard?.name)} onParametersChange{(payload) console.log(payload.source, payload.parameters)} / /MetabaseProvider ); }要点提醒dashboardId支持数字 ID 与entity_id字符串见 SdkDashboardId编辑能力需要当前用户具备对应权限supportsGuestEmbed: false意味着游客嵌入下不可用若需受控 回传的参数闭环请同时使用parameters与onParametersChange若仅需初始值使用initialParameters不要把parameters/initialParameters与hiddenParameters组合用于前端数据过滤存在安全风险只能用于界面整理。与 InteractiveDashboard 的选型对比维度InteractiveDashboardEditableDashboard钻取、点击行为、查看问题✅✅完整继承编辑态新增/更新问题、改布局与内容❌✅编辑入口动作EDIT_DASHBOARD等❌✅游客嵌入支持视版本而定❌supportsGuestEmbed: false从 InteractiveDashboard 文档 的签名可见其能力止步于drill downs, click behaviors, and the ability to view and click into questions而 EditableDashboard.md 明确定义其差异为as well as the ability to add and update questions, layout, and content within your dashboard。因此只读展示选StaticDashboard需要交互分析选InteractiveDashboard需要终端用户自助维护仪表盘内容时再选EditableDashboard。总结EditableDashboard是 Embedding SDK 中能力最完整的仪表盘组件它复用InteractiveDashboard的交互与钻取体系通过注入DASHBOARD_EDITING_ACTIONS编辑动作集合获得添加/更新问题、调整布局与内容的能力并通过SdkInternalNavigationProvider、useSdkControlledParameters等基础设施保证嵌入场景下的导航与受控参数语义。使用前请务必注意编辑能力意味着写操作需要真实认证用户不支持游客嵌入且参数过滤必须依赖后端权限而非前端隐藏控件。相关源码入口EditableDashboard.tsx、EditableDashboard.schema.ts、SdkDashboard.tsx。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考