Metabase Embedding SDK 中 CreateQuestion 组件的弃用说明与 InteractiveQuestion 迁移指南【免费下载链接】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本文围绕 CreateQuestion.md 这一 API 参考文档展开说明 Metabase Embedding SDKmetabase/embedding-sdk-react中CreateQuestion组件已正式弃用并给出以InteractiveQuestion questionIdnew /为替代方案的全量迁移指引包括new/new-native两种新建模式的语义、CreateQuestionProps完整属性清单、以及仓库源码与单元测试层面的验证依据。读完本文你将掌握在嵌入式 React 应用中安全替换弃用组件、继续使用新建问题能力的完整实操方案。一、CreateQuestion 组件签名与弃用状态在 Metabase Embedding SDK 的 API 参考体系中CreateQuestion.md 是 api 索引 中 CreateQuestion 一节的组成部分。该文档给出的组件签名如下function CreateQuestion(props: CreateQuestionProps | undefined): Element;三个关键信息项目内容参数props类型为CreateQuestionProps|undefined即属性对象可选返回值ReactElement即渲染出一个可嵌入的问题创建界面弃用标记文档中明确标注~~CreateQuestion~~删除线并给出替代方案在 api 索引 中CreateQuestion与CreateQuestionProps均被列为条目但组件名带删除线属于已弃用但保留文档供迁移参考的 API 形态。官方弃用说明CreateQuestion.md 文档的 Deprecated 一节是核心结论原文内容为UseInteractiveQuestion questionIdnew /instead.即不要再使用CreateQuestion组件请改用InteractiveQuestion组件并传入questionIdnew。这条迁移路径意味着新建问题的能力并未消失而是被统一收编到了更通用的InteractiveQuestion组件之下。二、CreateQuestionProps被继承的完整属性清单虽然组件本身被弃用但其承载的配置能力——即 CreateQuestionProps.md 中列出的全部属性——几乎原样延续到了InteractiveQuestionProps中对比 InteractiveQuestionProps.md 可发现属性集合高度一致。理解这些属性等于同时理解了迁移后的InteractiveQuestion的能力边界。完整属性表如下属性类型说明className?string添加到根元素的自定义 class 名dataPicker?EmbeddingDataPicker控制问题中数据源选择菜单设置为staged可使用完整数据选择器entityTypes?EmbeddingEntityType[]指定数据选择器中可用的实体类型数组height?Heightstring \| numberCSS 尺寸值指定组件高度hiddenParameters?string[]要隐藏的参数列表initialCollection?SdkCollectionId保存弹窗中集合选择器预选的集合与targetCollection不同选择器仍然可见用户可改选其他集合设置了targetCollection时此属性被忽略initialSqlParameters?SqlParameterValuesSQL 参数的初始值按 slug 键控仅在挂载时应用一次之后用户在控件中的编辑不会回传宿主isSaveEnabled?boolean是否显示保存按钮onBeforeSave?(question, context) Promisevoid保存前触发的回调仅在isSaveEnabled true时相关context含isNewQuestion标记onNavigateBack?() void用户点击返回按钮时触发的回调onRun?(question) void问题更新时触发包括用户点击编辑器中的Visualize按钮onSave?(question, context) void用户保存问题时触发仅在isSaveEnabled true时相关onSqlParametersChange?(payload: SqlParameterChangePayload) voidSQL 参数变化时触发payload 的source区分初始状态initial-state、用户编辑manual-change与自动更新auto-changeonVisualizationChange?(display) void可视化类型变化时触发display 取值覆盖objecttablebarlinepiescalarrowareacombopivotsmartscalargaugeprogressfunnelmapscatterboxplotwaterfallsankeytreemaplist等plugins?MetabasePluginsConfig插件配置sqlParameters?SqlParameterValues受控的 SQL 参数值按 slug 键控每次渲染都会替换问题的参数值需配合onSqlParametersChange保持与用户编辑同步style?CSSProperties添加到根元素的自定义 style 对象targetCollection?SdkCollectionId问题保存到的目标集合设置后会隐藏保存弹窗中的集合选择器仅对交互式问题适用title?SdkQuestionTitleProps是否显示问题标题以及是否用自定义标题替换默认标题默认显示width?Widthstring \| numberCSS 尺寸值指定组件宽度withAlerts?boolean是否允许在问题上设置告警withChartTypeSelector?boolean是否显示图表类型选择器及对应设置按钮仅在默认布局下相关withDownloads?boolean是否允许下载问题结果withEditorButton?boolean是否显示编辑器按钮仅在默认布局下相关其中几个属性在迁移到InteractiveQuestion后依然有效且常见isSaveEnabled控制保存流程、targetCollection/initialCollection控制保存位置、withDownloads/withAlerts控制能力开关、onBeforeSave/onSave钩入保存生命周期。三、替代方案InteractiveQuestion 与 questionIdnew3.1 SdkQuestionId 的四种取值替代方案的核心在于questionId属性其类型定义见 SdkQuestionId.mdtype SdkQuestionId number | new | new-native | SdkEntityId;官方文档给出的四种用法示例// 数值 ID取自问题 URL const questionId: SdkQuestionId 123; // 实体 ID 字符串 const questionId: SdkQuestionId abc123def456; // 新建 notebook 风格问题替代 CreateQuestion const questionId: SdkQuestionId new; // 新建原生 SQL 问题 const questionId: SdkQuestionId new-native;其中new正是文档指定的CreateQuestion替代值而new-native则对应新建原生 SQL 查询的模式。关于这两个取值在 InteractiveQuestionProps.md 的questionId属性说明中有明确语义new—— 显示用于创建新问题的 notebook 编辑器可视化查询构建器new-native—— 显示用于创建新原生问题的 SQL 编辑器。3.2 最小可用示例新建 notebook 问题仓库中 new-question.tsx 提供了开箱即用的完整示例import React from react; import { InteractiveQuestion, MetabaseProvider, defineMetabaseAuthConfig, } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://your-metabase.example.com, }); export default function App() { return ( MetabaseProvider authConfig{authConfig} InteractiveQuestion questionIdnew / /MetabaseProvider ); }要点拆解应用外层必须用MetabaseProvider包裹并通过defineMetabaseAuthConfig传入 Metabase 实例地址与认证配置将questionId固定为字符串new组件即渲染出 notebook 新建界面用户可以从零开始选择数据、聚合、可视化并保存这一写法完全等价于旧版CreateQuestion /的用途且无需任何额外包装。3.3 变体新建原生 SQL 问题若希望用户直接进入 SQL 编辑器参照 new-native-question.tsximport React from react; import { InteractiveQuestion, MetabaseProvider, defineMetabaseAuthConfig, } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://your-metabase.example.com, }); export default function App() { return ( MetabaseProvider authConfig{authConfig} InteractiveQuestion questionIdnew-native / /MetabaseProvider ); }两种模式只需切换questionId字符串即可。四、源码级验证new / new-native 的真实处理逻辑上述语义并非文档单方面约定在仓库前端源码中有直接实现证据。核心文件为 InteractiveQuestion.tsxconst isNewQuestion resolvedQuestionId new || resolvedQuestionId new-native;随后第 143-146 行在埋点上报中进一步区分两种新建模式isNewQuestion ? { id_new: resolvedQuestionId new, id_new_native: resolvedQuestionId new-native, is_save_enabled: isSaveEnabled, with_title: title ! false, with_downloads: withDownloads, with_alerts: withAlerts, } : { /* 非新建问题的上报字段 */ };此外该文件第 124-133 行的注释还说明了一个边界情形当通过query属性渲染例如 Metabotnavigate_to且未传questionId时会从 card 的dataset_query.type推导出应打开 notebook 还是 SQL 编辑器保证原生查询场景与new-native行为一致对应内部 issue EMB-2042。单元测试 InteractiveQuestion.unit.spec.tsx 中也有专门的测试分组describe(questionId: new, () { // 验证渲染 notebook 新建界面… });测试覆盖了questionId: new的默认渲染第 378 行setup({ questionId: new })以及dataPicker: staged开启完整数据选择器的组合第 392 行印证了新建模式 数据选择器配置是官方验证过的受支持用法。五、从 CreateQuestion 到 InteractiveQuestion 的迁移要点结合弃用文档、属性清单与源码实现迁移可按以下清单执行替换组件将CreateQuestion {...props} /改为InteractiveQuestion questionIdnew {...props} /若原先是新建 SQL 问题场景则使用questionIdnew-native。核对属性兼容性CreateQuestionProps中的className、style、width、height、title、isSaveEnabled、targetCollection、initialCollection、dataPicker、entityTypes、hiddenParameters、plugins、withDownloads、withAlerts、withChartTypeSelector、withEditorButton、onRun、onSave、onBeforeSave、onNavigateBack、onVisualizationChange、sqlParameters、initialSqlParameters、onSqlParametersChange等属性在InteractiveQuestionProps中均有对应项可直接平移。确认 Provider 就位InteractiveQuestion与旧组件一样依赖MetabaseProvider提供的认证与主题上下文迁移时不要遗漏。处理 SQL 参数涉及原生查询参数时用sqlParameters受控搭配onSqlParametersChange保持双向同步仅需初始值则用initialSqlParameters一次性应用。回归验证可参照仓库单元测试覆盖的两个维度——默认 notebook 渲染、dataPickerstaged完整数据选择器确认迁移后功能无回退。六、小结CreateQuestion是 Metabase Embedding SDK 中已被正式弃用的组件官方在 CreateQuestion.md 中给出的替代方案是InteractiveQuestion questionIdnew /。这一迁移并非功能裁剪其属性能力完整保留在InteractiveQuestionProps中新建 notebook 问题与新建原生 SQL 问题分别通过questionIdnew与questionIdnew-native表达并有 InteractiveQuestion.tsx 的源码逻辑与 InteractiveQuestion.unit.spec.tsx 的测试用例双重背书。新接入的开发者应直接使用InteractiveQuestion新建模式存量代码则按上文清单平滑迁移。【免费下载链接】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），仅供参考 
长河君 · 2026/9/10 1:23:47 · 阅读 1.2k Metabase Embedding SDK 中 CreateQuestion 组件的弃用说明与 InteractiveQuestion 迁移指南
Metabase Embedding SDK 中 CreateQuestion 组件的弃用说明与 InteractiveQuestion 迁移指南【免费下载链接】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本文围绕 CreateQuestion.md 这一 API 参考文档展开说明 Metabase Embedding SDKmetabase/embedding-sdk-react中CreateQuestion组件已正式弃用并给出以InteractiveQuestion questionIdnew /为替代方案的全量迁移指引包括new/new-native两种新建模式的语义、CreateQuestionProps完整属性清单、以及仓库源码与单元测试层面的验证依据。读完本文你将掌握在嵌入式 React 应用中安全替换弃用组件、继续使用新建问题能力的完整实操方案。一、CreateQuestion 组件签名与弃用状态在 Metabase Embedding SDK 的 API 参考体系中CreateQuestion.md 是 api 索引 中 CreateQuestion 一节的组成部分。该文档给出的组件签名如下function CreateQuestion(props: CreateQuestionProps | undefined): Element;三个关键信息项目内容参数props类型为CreateQuestionProps|undefined即属性对象可选返回值ReactElement即渲染出一个可嵌入的问题创建界面弃用标记文档中明确标注~~CreateQuestion~~删除线并给出替代方案在 api 索引 中CreateQuestion与CreateQuestionProps均被列为条目但组件名带删除线属于已弃用但保留文档供迁移参考的 API 形态。官方弃用说明CreateQuestion.md 文档的 Deprecated 一节是核心结论原文内容为UseInteractiveQuestion questionIdnew /instead.即不要再使用CreateQuestion组件请改用InteractiveQuestion组件并传入questionIdnew。这条迁移路径意味着新建问题的能力并未消失而是被统一收编到了更通用的InteractiveQuestion组件之下。二、CreateQuestionProps被继承的完整属性清单虽然组件本身被弃用但其承载的配置能力——即 CreateQuestionProps.md 中列出的全部属性——几乎原样延续到了InteractiveQuestionProps中对比 InteractiveQuestionProps.md 可发现属性集合高度一致。理解这些属性等于同时理解了迁移后的InteractiveQuestion的能力边界。完整属性表如下属性类型说明className?string添加到根元素的自定义 class 名dataPicker?EmbeddingDataPicker控制问题中数据源选择菜单设置为staged可使用完整数据选择器entityTypes?EmbeddingEntityType[]指定数据选择器中可用的实体类型数组height?Heightstring \| numberCSS 尺寸值指定组件高度hiddenParameters?string[]要隐藏的参数列表initialCollection?SdkCollectionId保存弹窗中集合选择器预选的集合与targetCollection不同选择器仍然可见用户可改选其他集合设置了targetCollection时此属性被忽略initialSqlParameters?SqlParameterValuesSQL 参数的初始值按 slug 键控仅在挂载时应用一次之后用户在控件中的编辑不会回传宿主isSaveEnabled?boolean是否显示保存按钮onBeforeSave?(question, context) Promisevoid保存前触发的回调仅在isSaveEnabled true时相关context含isNewQuestion标记onNavigateBack?() void用户点击返回按钮时触发的回调onRun?(question) void问题更新时触发包括用户点击编辑器中的Visualize按钮onSave?(question, context) void用户保存问题时触发仅在isSaveEnabled true时相关onSqlParametersChange?(payload: SqlParameterChangePayload) voidSQL 参数变化时触发payload 的source区分初始状态initial-state、用户编辑manual-change与自动更新auto-changeonVisualizationChange?(display) void可视化类型变化时触发display 取值覆盖objecttablebarlinepiescalarrowareacombopivotsmartscalargaugeprogressfunnelmapscatterboxplotwaterfallsankeytreemaplist等plugins?MetabasePluginsConfig插件配置sqlParameters?SqlParameterValues受控的 SQL 参数值按 slug 键控每次渲染都会替换问题的参数值需配合onSqlParametersChange保持与用户编辑同步style?CSSProperties添加到根元素的自定义 style 对象targetCollection?SdkCollectionId问题保存到的目标集合设置后会隐藏保存弹窗中的集合选择器仅对交互式问题适用title?SdkQuestionTitleProps是否显示问题标题以及是否用自定义标题替换默认标题默认显示width?Widthstring \| numberCSS 尺寸值指定组件宽度withAlerts?boolean是否允许在问题上设置告警withChartTypeSelector?boolean是否显示图表类型选择器及对应设置按钮仅在默认布局下相关withDownloads?boolean是否允许下载问题结果withEditorButton?boolean是否显示编辑器按钮仅在默认布局下相关其中几个属性在迁移到InteractiveQuestion后依然有效且常见isSaveEnabled控制保存流程、targetCollection/initialCollection控制保存位置、withDownloads/withAlerts控制能力开关、onBeforeSave/onSave钩入保存生命周期。三、替代方案InteractiveQuestion 与 questionIdnew3.1 SdkQuestionId 的四种取值替代方案的核心在于questionId属性其类型定义见 SdkQuestionId.mdtype SdkQuestionId number | new | new-native | SdkEntityId;官方文档给出的四种用法示例// 数值 ID取自问题 URL const questionId: SdkQuestionId 123; // 实体 ID 字符串 const questionId: SdkQuestionId abc123def456; // 新建 notebook 风格问题替代 CreateQuestion const questionId: SdkQuestionId new; // 新建原生 SQL 问题 const questionId: SdkQuestionId new-native;其中new正是文档指定的CreateQuestion替代值而new-native则对应新建原生 SQL 查询的模式。关于这两个取值在 InteractiveQuestionProps.md 的questionId属性说明中有明确语义new—— 显示用于创建新问题的 notebook 编辑器可视化查询构建器new-native—— 显示用于创建新原生问题的 SQL 编辑器。3.2 最小可用示例新建 notebook 问题仓库中 new-question.tsx 提供了开箱即用的完整示例import React from react; import { InteractiveQuestion, MetabaseProvider, defineMetabaseAuthConfig, } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://your-metabase.example.com, }); export default function App() { return ( MetabaseProvider authConfig{authConfig} InteractiveQuestion questionIdnew / /MetabaseProvider ); }要点拆解应用外层必须用MetabaseProvider包裹并通过defineMetabaseAuthConfig传入 Metabase 实例地址与认证配置将questionId固定为字符串new组件即渲染出 notebook 新建界面用户可以从零开始选择数据、聚合、可视化并保存这一写法完全等价于旧版CreateQuestion /的用途且无需任何额外包装。3.3 变体新建原生 SQL 问题若希望用户直接进入 SQL 编辑器参照 new-native-question.tsximport React from react; import { InteractiveQuestion, MetabaseProvider, defineMetabaseAuthConfig, } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://your-metabase.example.com, }); export default function App() { return ( MetabaseProvider authConfig{authConfig} InteractiveQuestion questionIdnew-native / /MetabaseProvider ); }两种模式只需切换questionId字符串即可。四、源码级验证new / new-native 的真实处理逻辑上述语义并非文档单方面约定在仓库前端源码中有直接实现证据。核心文件为 InteractiveQuestion.tsxconst isNewQuestion resolvedQuestionId new || resolvedQuestionId new-native;随后第 143-146 行在埋点上报中进一步区分两种新建模式isNewQuestion ? { id_new: resolvedQuestionId new, id_new_native: resolvedQuestionId new-native, is_save_enabled: isSaveEnabled, with_title: title ! false, with_downloads: withDownloads, with_alerts: withAlerts, } : { /* 非新建问题的上报字段 */ };此外该文件第 124-133 行的注释还说明了一个边界情形当通过query属性渲染例如 Metabotnavigate_to且未传questionId时会从 card 的dataset_query.type推导出应打开 notebook 还是 SQL 编辑器保证原生查询场景与new-native行为一致对应内部 issue EMB-2042。单元测试 InteractiveQuestion.unit.spec.tsx 中也有专门的测试分组describe(questionId: new, () { // 验证渲染 notebook 新建界面… });测试覆盖了questionId: new的默认渲染第 378 行setup({ questionId: new })以及dataPicker: staged开启完整数据选择器的组合第 392 行印证了新建模式 数据选择器配置是官方验证过的受支持用法。五、从 CreateQuestion 到 InteractiveQuestion 的迁移要点结合弃用文档、属性清单与源码实现迁移可按以下清单执行替换组件将CreateQuestion {...props} /改为InteractiveQuestion questionIdnew {...props} /若原先是新建 SQL 问题场景则使用questionIdnew-native。核对属性兼容性CreateQuestionProps中的className、style、width、height、title、isSaveEnabled、targetCollection、initialCollection、dataPicker、entityTypes、hiddenParameters、plugins、withDownloads、withAlerts、withChartTypeSelector、withEditorButton、onRun、onSave、onBeforeSave、onNavigateBack、onVisualizationChange、sqlParameters、initialSqlParameters、onSqlParametersChange等属性在InteractiveQuestionProps中均有对应项可直接平移。确认 Provider 就位InteractiveQuestion与旧组件一样依赖MetabaseProvider提供的认证与主题上下文迁移时不要遗漏。处理 SQL 参数涉及原生查询参数时用sqlParameters受控搭配onSqlParametersChange保持双向同步仅需初始值则用initialSqlParameters一次性应用。回归验证可参照仓库单元测试覆盖的两个维度——默认 notebook 渲染、dataPickerstaged完整数据选择器确认迁移后功能无回退。六、小结CreateQuestion是 Metabase Embedding SDK 中已被正式弃用的组件官方在 CreateQuestion.md 中给出的替代方案是InteractiveQuestion questionIdnew /。这一迁移并非功能裁剪其属性能力完整保留在InteractiveQuestionProps中新建 notebook 问题与新建原生 SQL 问题分别通过questionIdnew与questionIdnew-native表达并有 InteractiveQuestion.tsx 的源码逻辑与 InteractiveQuestion.unit.spec.tsx 的测试用例双重背书。新接入的开发者应直接使用InteractiveQuestion新建模式存量代码则按上文清单平滑迁移。【免费下载链接】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），仅供参考