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 SDK（@metabase/embedding-sdk-react）中CreateQuestion组件已正式弃用，并给出以<InteractiveQuestion questionId="new" />为替代方案的全量迁移指引，包括"new"/"new-native"两种新建模式的语义、CreateQuestionProps完整属性清单、以及仓库源码与单元测试层面的验证依据。读完本文，你将掌握在嵌入式 React 应用中安全替换弃用组件、继续使用"新建问题"能力的完整实操方案。

一、CreateQuestion 组件：签名与弃用状态

在 Metabase Embedding SDK 的 API 参考体系中，CreateQuestion.md 是 api 索引 中 "CreateQuestion" 一节的组成部分。该文档给出的组件签名如下：

function CreateQuestion(props: CreateQuestionProps | undefined): Element;

三个关键信息：

在 api 索引 中，CreateQuestion与CreateQuestionProps均被列为条目，但组件名带删除线，属于"已弃用但保留文档供迁移参考"的 API 形态。

官方弃用说明

CreateQuestion.md 文档的 "Deprecated" 一节是核心结论，原文内容为：

Use<InteractiveQuestion questionId="new" />instead.

即：不要再使用CreateQuestion组件，请改用InteractiveQuestion组件，并传入questionId="new"。这条迁移路径意味着"新建问题"的能力并未消失，而是被统一收编到了更通用的InteractiveQuestion组件之下。

二、CreateQuestionProps：被继承的完整属性清单

虽然组件本身被弃用，但其承载的配置能力——即 CreateQuestionProps.md 中列出的全部属性——几乎原样延续到了InteractiveQuestionProps中（对比 InteractiveQuestionProps.md 可发现属性集合高度一致）。理解这些属性，等于同时理解了迁移后的InteractiveQuestion的能力边界。

完整属性表如下：

其中几个属性在迁移到InteractiveQuestion后依然有效且常见：isSaveEnabled控制保存流程、targetCollection/initialCollection控制保存位置、withDownloads/withAlerts控制能力开关、onBeforeSave/onSave钩入保存生命周期。

三、替代方案：InteractiveQuestion 与 questionId="new"

3.1 SdkQuestionId 的四种取值

替代方案的核心在于questionId属性，其类型定义见 SdkQuestionId.md：

type 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 questionId="new" /> </MetabaseProvider> ); }

要点拆解：

1. 应用外层必须用MetabaseProvider包裹，并通过defineMetabaseAuthConfig传入 Metabase 实例地址与认证配置；
2. 将questionId固定为字符串"new"，组件即渲染出 notebook 新建界面，用户可以从零开始选择数据、聚合、可视化并保存；
3. 这一写法完全等价于旧版<CreateQuestion />的用途，且无需任何额外包装。

3.3 变体：新建原生 SQL 问题

若希望用户直接进入 SQL 编辑器，参照 new-native-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 questionId="new-native" /> </MetabaseProvider> ); }

两种模式只需切换questionId字符串即可。

四、源码级验证：new / new-native 的真实处理逻辑

上述语义并非文档单方面约定，在仓库前端源码中有直接实现证据。核心文件为 InteractiveQuestion.tsx：

const 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 的迁移要点

结合弃用文档、属性清单与源码实现，迁移可按以下清单执行：

1. 替换组件：将<CreateQuestion {...props} />改为<InteractiveQuestion questionId="new" {...props} />；若原先是"新建 SQL 问题"场景，则使用questionId="new-native"。
2. 核对属性兼容性：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中均有对应项，可直接平移。
3. 确认 Provider 就位：InteractiveQuestion与旧组件一样依赖MetabaseProvider提供的认证与主题上下文，迁移时不要遗漏。
4. 处理 SQL 参数：涉及原生查询参数时，用sqlParameters（受控）搭配onSqlParametersChange保持双向同步；仅需初始值则用initialSqlParameters（一次性应用）。
5. 回归验证：可参照仓库单元测试覆盖的两个维度——默认 notebook 渲染、dataPicker="staged"完整数据选择器，确认迁移后功能无回退。

六、小结

CreateQuestion是 Metabase Embedding SDK 中已被正式弃用的组件，官方在 CreateQuestion.md 中给出的替代方案是<InteractiveQuestion questionId="new" />。这一迁移并非功能裁剪：其属性能力完整保留在InteractiveQuestionProps中，"新建 notebook 问题"与"新建原生 SQL 问题"分别通过questionId="new"与questionId="new-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