Metabase Embedding SDK CreateQuestion 组件属性完全指南嵌入式新建问题的创建、保存与回调机制【免费下载链接】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/metabaseCreateQuestion是 Metabase Embedding SDKfrontend/src/embedding-sdk-bundle中用于在宿主应用中内嵌新建问题编辑器的公开组件它允许终端用户直接在你的产品界面里从零创建、编辑并保存一个问题Question。本文以其属性参考文档 CreateQuestionProps.md 为骨架结合仓库源码逐项解析全部 23 个属性Props的含义、类型、默认行为与回调触发时机并给出可直接运行的 React 集成示例帮助你完全掌控嵌入问题的数据源选择、SQL 参数联动、保存流程与可视化切换等细节。CreateQuestion 是什么与 InteractiveQuestion 的关系CreateQuestion本质上是一个轻量封装。在 CreateQuestion.tsx 中可以看到它的完整定义export type CreateQuestionProps Omit PartialInteractiveQuestionBaseProps, children ; const CreateQuestionInner (props: CreateQuestionProps {}) ( InteractiveQuestion {...props} questionIdnew / ); export const CreateQuestion withPublicComponentWrapper(CreateQuestionInner, { supportsGuestEmbed: false, }) as typeof CreateQuestionInner;从源码结构可以推断出三个关键事实CreateQuestionProps是InteractiveQuestion基础属性的子集它通过OmitPartialInteractiveQuestionBaseProps, children派生出自己的类型因此本篇文章属性表中几乎所有属性在InteractiveQuestion组件上同样适用。内部固定传入questionIdnew组件在渲染时强制将问题 ID 设为new这正是新建问题模式的标志。在 InteractiveQuestion.tsx 中resolvedQuestionId new || resolvedQuestionId new-native会被判定为isNewQuestion从而驱动新建状态下的 UI 与行为。不支持 Guest Embed访客嵌入supportsGuestEmbed: false表明该组件要求认证用户环境这一点与InteractiveQuestion一致。另外官方文档在 CreateQuestion.md 中明确标记该组件为Deprecated已废弃推荐改用InteractiveQuestion questionIdnew /直接实现相同能力。即便如此由于CreateQuestion仍在 SDK 公开 API 中保留且其属性体系完整继承了InteractiveQuestion理解这份属性表对两种用法都有直接价值。属性总览完整属性表CreateQuestion接受的唯一参数props类型为CreateQuestionProps | undefined返回值是 React 的Element。下表完整列出全部属性PropertyTypeDescriptionclassName?string添加到根元素的自定义 CSS 类名。dataPicker?EmbeddingDataPicker控制问题中数据源选择菜单的形态设置为dataPicker staged可启用完整版数据选择器。entityTypes?EmbeddingEntityType[]指定数据选择器中可用的实体类型如表、模型、问题、指标等数组。height?Heightstring \| number数值或字符串形式的 CSS 尺寸值指定组件高度。hiddenParameters?string[]需要隐藏的参数列表。initialCollection?SdkCollectionId保存弹窗的收藏夹选择器中预选的目标集合。与targetCollection不同此时选择器仍然可见用户可改选其他集合当targetCollection已设置时该属性被忽略。initialSqlParameters?SqlParameterValuesSQL 参数的初始值以 slug 为键。仅在挂载时应用一次之后用户在组件内的修改不会回传给宿主应用。每个参数的具体行为见下文SQL 参数一节。isSaveEnabled?boolean是否显示保存按钮。onBeforeSave?(question:MetabaseQuestion|undefined,context: {isNewQuestion:boolean; }) Promisevoid保存前触发的回调函数仅在isSaveEnabled true时相关。onNavigateBack?() void用户点击返回按钮时触发的回调函数。onRun?(question:MetabaseQuestion|undefined) void问题更新时触发包括用户点击问题编辑器中的Visualize按钮。onSave?(question:MetabaseQuestion,context: {dashboardTabId?:number;isNewQuestion:boolean; }) void用户保存问题时触发的回调仅在isSaveEnabled true时相关。onSqlParametersChange?(payload:SqlParameterChangePayload) voidSQL 参数变化时触发。payload.source区分初始加载状态initial-state、用户 UI 编辑manual-change与自动更新auto-change。onVisualizationChange?(display:object|table|bar|line|pie|scalar|row|area|combo|pivot|smartscalar|gauge|progress|funnel|map|scatter|boxplot|waterfall|sankey|treemap|list) void可视化类型切换时触发的回调。plugins?MetabasePluginsConfig插件配置对象官方文档未给出额外说明具体能力取决于插件配置类型定义。sqlParameters?SqlParameterValues受控的 SQL 参数值以 slug 为键。每次渲染时该对象都会替换问题的参数值需配合onSqlParametersChange保持与用户编辑同步。style?CSSProperties添加到根元素的自定义样式对象。targetCollection?SdkCollectionId问题保存到的目标集合。设置后将隐藏保存弹窗中的集合选择器仅对交互式问题适用。title?SdkQuestionTitleProps控制问题标题是否显示并允许用自定义标题替换默认问题标题。默认显示。width?Widthstring \| number数值或字符串形式的 CSS 尺寸值指定组件宽度。withAlerts?boolean是否允许在问题上设置告警Alerts。withChartTypeSelector?boolean是否显示图表类型选择器及对应的设置按钮。仅在使用默认布局时相关。withDownloads?boolean是否允许在问题中下载结果。withEditorButton?boolean是否显示编辑器按钮。仅在使用默认布局时相关。布局与外观尺寸、类名、样式与标题CreateQuestion在宿主页面中渲染为一个根元素你可以通过三类属性完全控制它的外观width/height接受数字或字符串形式的 CSS 尺寸值例如width{800}、height60vh。这对应底层SdkQuestion根容器对外暴露的尺寸控制。className自定义类名会被追加到根元素上便于你用全局样式表或 CSS 模块做定位与覆写。style直接传入 ReactCSSProperties对象适合在组件内部做内联样式定制。title类型为SdkQuestionTitleProps。默认情况下问题标题是显示的你可以通过该属性隐藏标题或用自定义文本替代默认的问题标题适合在已有自身页头设计的宿主应用中避免标题重复。数据源选择dataPicker、entityTypes 与集合预选新建问题的第一步是让用户挑选数据源相关属性共同控制这一交互dataPicker类型为EmbeddingDataPicker取值staged | flat。文档明确指出设置dataPicker staged可启用完整版分步式数据选择器而默认的扁平数据选择器只列出可直接选择的实体。从 InteractiveQuestion.unit.spec.tsx 的测试用例可以看到当questionIdnew且使用默认数据选择器时界面会渲染出 Pick your starting data 按钮和对应的数据选择弹窗弹窗内列出可用的模型如 Orders model当传入dataPicker: staged时会走另一套分步决策逻辑。entityTypes类型为EmbeddingEntityType[]用于白名单式地指定数据选择器里可用的实体类型例如只允许选模型和原生问题而隐藏底层的数据库表。它配合dataPicker一起决定能选什么。initialCollection指定保存弹窗中收藏夹选择器的预选集合SdkCollectionId。关键语义是选择器仍然可见用户可以改选其他集合因此它只是一个初始选中项。文档同时强调一旦设置了targetCollectioninitialCollection会被忽略。targetCollection直接把问题固定保存到某个集合并隐藏保存弹窗里的集合选择器仅对交互式问题适用。适合在保存到固定工作区的产品流程中使用。SQL 参数初始值、受控值与变更回调对于原生 SQL 问题参数控制是CreateQuestion最值得关注的能力之一涉及三个属性initialSqlParameters一次性初始值类型为SqlParameterValues本质上是Recordstring, string | number | boolean | (string | number | boolean | null)[] | null | undefined以参数 slug 为键。它的行为是设置为某个值 → 应用该值设置为null→ 严格清空该参数忽略其默认值省略该键或设为undefined→ 回退到参数默认值无默认值则为null。关键限制是只在组件挂载时应用一次用户在问题编辑器中的后续修改不会反向同步到宿主应用。它适合进入页面时携带一份预设筛选条件的场景。sqlParameters受控值同样是 slug 键控的SqlParameterValues但语义完全不同每次渲染时该对象都会整体替换问题的参数值是真正的受控组件模式。其逐参数行为与initialSqlParameters一致值 /null严格清空 / 省略回退默认。文档建议将其与onSqlParametersChange配对使用从而把组件内的用户编辑状态提升到宿主应用实现完全受控的参数双向同步。onSqlParametersChange变更回调回调载荷类型为SqlParameterChangePayload其source字段用于区分三种触发来源initial-state加载时的初始状态manual-change用户在 UI 中的手动编辑auto-change由系统自动更新如参数联动、默认值解析等。借助source宿主应用可以精确判断应如何响应例如只在manual-change时更新自己的受控状态避免把回显动作再次写回组件造成循环。保存流程isSaveEnabled、onBeforeSave 与 onSave新建问题的终点是保存这一流程由三个属性共同编排isSaveEnabled布尔开关决定是否显示保存按钮。关闭后用户只能创建与编辑问题无法落库。onBeforeSave保存动作发生前触发的异步回调接收(question, context)其中question为MetabaseQuestion可能为undefinedcontext提供isNewQuestion标志。返回Promisevoid意味着你可以在真正保存前执行异步校验、弹窗确认或附加副作用。仅当isSaveEnabled true时相关。onSave保存成功后触发的同步回调接收(question, context)。与onBeforeSave不同这里的question必然存在context除了isNewQuestion外还包含可选的dashboardTabId?当问题保存进某个仪表盘标签页时携带。典型用途是保存后通知宿主路由跳转、刷新列表或埋点上报。导航与运行onNavigateBack、onRun 与 onVisualizationChange这组回调对应问题编辑过程中的关键交互节点onNavigateBack用户点击返回按钮时触发无参数。宿主应用通常用它退出内嵌的编辑视图、切回自己的页面。onRun问题更新时触发含点击编辑器中的Visualize按钮回调携带最新的MetabaseQuestion可能为undefined。它是数据结果变化的通用监听点可用于在宿主侧同步展示元信息。onVisualizationChange可视化类型切换时触发回调参数是 21 种显示类型之一object、table、bar、line、pie、scalar、row、area、combo、pivot、smartscalar、gauge、progress、funnel、map、scatter、boxplot、waterfall、sankey、treemap、list。宿主应用可据此联动自己的图表切换器或分析偏好设置。功能开关hiddenParameters、withAlerts、withDownloads 与布局开关最后一组属性用于裁剪编辑器暴露给终端用户的能力面hiddenParametersstring[]列出要隐藏的参数按参数 slug适合把内部参数从用户界面中屏蔽掉。withAlerts布尔值启用后在问题上可设置告警Alerts让用户把问题结果转为定时通知。withDownloads布尔值启用后允许用户下载问题结果导出 CSV 等。withChartTypeSelector布尔值控制图表类型选择器与对应设置按钮是否显示。仅在使用默认布局时相关——当你通过子组件自定义布局如InteractiveQuestion.ChartTypeDropdown时该开关不生效。withEditorButton布尔值控制编辑器按钮是否显示同样仅在使用默认布局时相关。从源码看 new 问题的判定与渲染理解questionIdnew的底层逻辑有助于正确使用上述属性。在 InteractiveQuestion.tsx 中组件通过resolvedQuestionId new || resolvedQuestionId new-native判定isNewQuestion并以此为依据决定埋点上报的id_new/id_new_native标记。其中resolvedQuestionId由 SdkAdHocQuestion/utils.ts 中的resolveQuestionId函数计算从 URL slug 提取实体 ID如42-my-question→42若无 slug 且反序列化卡片是原生查询dataset_query.type native返回new-native即新建 SQL 编辑器模式其余情况返回null即新建笔记本模式。这解释了为什么CreateQuestion /与InteractiveQuestion questionIdnew /会直接进入数据源选择与新建编辑器流程——它们都绕过了已保存问题的加载分支。测试用例 InteractiveQuestion.unit.spec.tsx 验证了questionIdnew时会渲染 Pick your starting data 数据选择器与查询编辑器SDK 自带的 CreateQuestion.stories.tsx 则展示了组件在 Storybook 环境下的标准用法包裹CommonSdkStoryWrapper、以Flex布局承载组件实例。完整示例一个可运行的 CreateQuestion 集成综合以上属性下面给出一个贴近实战的完整示例覆盖数据源控制、SQL 参数受控、保存回调与可视化监听import { useState } from react; import { CreateQuestion, MetabaseProvider, type CreateQuestionProps, } from metabase/embedding-sdk-react; const authConfig { metabaseInstanceUrl: https://metabase.example.com, getToken: () Promise.resolve(your-jwt-token), }; export default function QuestionCreator() { const [sqlParams, setSqlParams] useState({ category: Gadgets }); const props: CreateQuestionProps { // —— 布局与外观 —— width: 960, height: 70vh, title: false, // 隐藏默认标题由宿主页面自行提供标题 // —— 数据源选择 —— dataPicker: staged, // 启用完整版分步数据选择器 entityTypes: [model, question], // 只允许选择模型与已保存问题 targetCollection: 5, // 固定保存到集合 5并隐藏集合选择器 // —— SQL 参数受控 —— sqlParameters: sqlParams, onSqlParametersChange: (payload) { // payload.source: initial-state | manual-change | auto-change if (payload.source manual-change) { setSqlParams(payload.params as typeof sqlParams); } }, // —— 保存流程 —— isSaveEnabled: true, onBeforeSave: async (question, { isNewQuestion }) { console.log(即将保存新建%s, isNewQuestion, question?.id()); // 在这里做异步校验例如检查权限或命名规范 }, onSave: (question, { isNewQuestion, dashboardTabId }) { console.log(已保存question id , question.id(), dashboardTabId); }, // —— 导航与运行 —— onNavigateBack: () history.back(), onRun: (question) console.log(问题已运行, question?.displayName()), onVisualizationChange: (display) console.log(可视化切换为, display), // —— 功能开关 —— hiddenParameters: [internal_tenant_id], withAlerts: true, withDownloads: true, withChartTypeSelector: true, withEditorButton: true, }; return ( MetabaseProvider authConfig{authConfig} CreateQuestion {...props} / /MetabaseProvider ); }迁移建议从 CreateQuestion 到 InteractiveQuestion官方已在 CreateQuestion.md 中标记CreateQuestion为废弃推荐的迁移方式是在组件树中替换为InteractiveQuestion questionIdnew /import { InteractiveQuestion } from metabase/embedding-sdk-react; export default function QuestionCreator() { return InteractiveQuestion questionIdnew /* 其余属性与本文章属性表完全一致 */ /; }由于CreateQuestionProps本质上是InteractiveQuestionBaseProps的部分子集本文属性表中的绝大多数属性dataPicker、entityTypes、sqlParameters、isSaveEnabled、onSave、withAlerts等在迁移后无需改动即可继续生效只有极少数仅存在于InteractiveQuestion的专属能力如通过children自定义子组件布局、query内部属性需要额外关注。结合本文对每个属性语义的拆解你可以直接对照属性表完成迁移与验证。【免费下载链接】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），仅供参考