Metabase 嵌入 SDK 的 SdkQuestionProps 全解：交互式问题组件的 Props 体系与实战用法

Metabase 嵌入 SDK 的 SdkQuestionProps 全解交互式问题组件的 Props 体系与实战用法【免费下载链接】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/metabaseSdkQuestionProps 是 Metabase React 嵌入 SDKEmbedding SDK中承载问题Question渲染与交互能力的核心 Props 类型由InteractiveQuestion、StaticQuestion以及仪表盘下钻drill-through等组件统一消费。本文以该类型的完整属性表为骨架逐一拆解问题标识、SQL 参数双向同步、保存流程、回调事件、功能开关与布局样式等 27 个属性的语义、取值约束与源码级实现细节帮助你在此基础上精准定制嵌入页面里的数据分析体验。SdkQuestionProps 在 SDK 组件体系中的位置在 Metabase 嵌入 SDK 中SdkQuestionProps是底层SdkQuestion组件的 Props 类型定义于 frontend/src/embedding-sdk-bundle/components/public/SdkQuestion/SdkQuestion.tsx。从源码结构看它由两部分组合而成SdkQuestionDefaultViewProps负责默认布局下的高度、宽度、类名、内联样式、标题显示、图表类型选择器与编辑器按钮等展示层配置SdkQuestionProviderProps的公开子集负责onBeforeSave、onSave、entityTypes、dataPicker、isSaveEnabled、initialSqlParameters、withDownloads、withAlerts、targetCollection、initialCollection、onRun等业务能力。而对外暴露的InteractiveQuestion组件见 InteractiveQuestion.tsx通过OmitSdkQuestionProps, token | questionId | clickActionMode | navigateToNewCard | backToDashboard派生自己的基础 Props再与SdkQuestionEntityPublicProps合并形成InteractiveQuestionProps。因此理解SdkQuestionProps就等于理解了 SDK 中一切问题型组件的配置模型。问题身份 PropsquestionId / card / token 的四种互斥组合questionId、card、token三个属性用于确定渲染什么问题它们不是随意可同时使用的而是受SdkQuestionEntityPublicProps见 docs/embedding/sdk/api/snippets/SdkQuestionEntityPublicProps.md约束的互斥联合类型四种合法形态如下形态用法{ questionId: SdkQuestionId \| null }通过问题 ID 渲染已保存的问题最常用{ token: SdkEntityToken \| null }通过 guest embed 的 JWT token 渲染支持访客嵌入{ card: string \| MetabaseCard }渲染一个不保存的临时ad-hoc问题{ query: MetabaseQueryObject \| null }渲染由useMetabaseQueryObject创建的基于数据表的临时查询questionId的类型为SdkQuestionId见 SdkQuestionId.md支持四种取值数字 ID取自问题访问链接如http://localhost:3000/question/1-my-question中的1字符串 entity_id通过 API 直接访问或使用 SDK Collection Browser 获取问题对象时取entity_id键对应的值如abc123def456new显示 notebook 编辑器用于创建新问题new-native显示 SQL 编辑器用于创建新的原生native问题。// 渲染已保存问题数字 ID 或 entity_id InteractiveQuestion questionId{123} / // 打开 notebook 编辑器创建新问题 InteractiveQuestion questionIdnew / // 打开 SQL 编辑器创建新原生查询 InteractiveQuestion questionIdnew-native /在源码中InteractiveQuestionInner会先对传入的card/query调用resolveDeserializedCard进行反序列化再据此解析questionId当通过query渲染时例如 Metabot 的navigate_to场景会从反序列化后的 card 中推导questionId从而让原生查询正确打开 SQL 编辑器。SQL 参数三件套initialSqlParameters / sqlParameters / onSqlParametersChange / hiddenParameters面向 SQL 原生问题SDK 提供了一套初始值 受控值 变更回调的完整参数同步模型这是SdkQuestionProps中信息量最大的一组属性。SqlParameterValues是一个以参数 slug 为键的 Record见 SqlParameterValues.md值为标量、数组或null/undefinedtype SqlParameterValues Record string, | string | number | boolean | (string | number | boolean | null)[] | null | undefined ;三个属性对单个参数的三态语义值 / null / 省略处理方式不同这是最容易踩坑的地方属性机制值为 X值为null省略或undefinedinitialSqlParameters一次性初始化仅在组件挂载mount时应用之后用户在界面上的修改不会回写给宿主应用该值严格清空忽略参数默认值回退到参数默认值无默认值则为nullsqlParameters受控模式每次渲染都会用该对象整体替换问题的参数值使用该值即使有默认值也清空使用默认值无默认值则为nullonSqlParametersChange变更回调payload携带defaultParameters、parameters和source———其中onSqlParametersChange的 payload 类型为SqlParameterChangePayload见 SqlParameterChangePayload.md其source字段取值见 SqlParameterChangeSource.mdinitial-state问题加载时首次应用的状态每个问题加载只触发一次manual-change用户在界面中编辑参数auto-change自动更新场景例如把归一化后的值回传给父组件。官方推荐将sqlParameters与onSqlParametersChange配对使用形成受控同步const [params, setParams] useStateSqlParameterValues({}); InteractiveQuestion questionId{42} sqlParameters{params} onSqlParametersChange{({ parameters }) setParams(parameters)} /;此外hiddenParametersstring[]可传入一组参数名用于在界面上隐藏对应的参数控件。保存流程isSaveEnabled / onBeforeSave / onSave / targetCollection / initialCollection这组属性共同决定问题能否被保存、保存到哪里、保存前后如何干预isSaveEnabledboolean是否显示保存按钮。它是onBeforeSave、onSave生效的前提——文档明确标注两者Only relevant whenisSaveEnabled true。onBeforeSave保存前触发的回调接收(question: MetabaseQuestion | undefined, context: { isNewQuestion: boolean })返回Promisevoid可在保存前执行校验或异步预处理。onSave保存成功后的回调接收(question: MetabaseQuestion, context: { dashboardTabId?: number; isNewQuestion: boolean })。MetabaseQuestion对象包含id、entityId、name、description、isSavedQuestion等字段见 MetabaseQuestion.md其中isSavedQuestion可用于区分新旧问题。targetCollectionSdkCollectionId保存问题的目标集合设置后会隐藏保存弹窗中的集合选择器仅对交互式问题生效。initialCollectionSdkCollectionId在保存弹窗的集合选择器中预选某个集合。与targetCollection不同此时选择器仍然可见用户可改选其他集合且当设置了targetCollection时本属性被忽略。SdkCollectionId见 SdkCollectionId.md的取值为number | personal | root | tenant | SdkEntityId其中personal、root、tenant是 SDK 提供的语义化集合标识。交互回调onRun / onNavigateBack / onVisualizationChangeSdkQuestionProps提供三个核心事件回调onRun每当问题被更新时触发包括用户点击问题编辑器中的Visualize按钮回调收到(question: MetabaseQuestion | undefined)可用于在每次查询执行后把最新问题对象同步到宿主状态。onNavigateBack用户点击返回按钮时触发() void适用于下钻drill-through或内嵌导航场景。onVisualizationChange可视化类型切换时触发回调参数display是 22 种可视化类型的字面量联合object | table | bar | line | pie | scalar | row | area | combo | pivot | smartscalar | gauge | progress | funnel | map | scatter | boxplot | waterfall | sankey | treemap | list。功能开关与界面元素withAlerts / withDownloads / withChartTypeSelector / withEditorButton / titlewithAlertsboolean启用为问题创建告警alert的能力。在源码中默认值为false。withDownloadsboolean启用下载问题结果的能力。源码默认值为false。withChartTypeSelectorboolean是否显示图表类型选择器及对应的设置按钮仅在使用默认布局时相关。源码默认值为true。withEditorButtonboolean是否显示编辑器editor按钮同样仅对默认布局生效。源码默认值为true。titleSdkQuestionTitleProps见 SdkQuestionTitleProps.md控制问题标题是否显示并允许用自定义标题替换默认标题。其类型为boolean | undefined | ReactNode | (() ReactNode)——传入false隐藏标题传入任意 React 节点或返回节点的函数则渲染自定义标题。默认显示。InteractiveQuestion questionId{123} title{false} // 隐藏标题 withDownloads // 允许下载结果 withAlerts // 允许设置告警 withChartTypeSelector{false} // 隐藏图表类型选择器默认布局 withEditorButton{false} // 隐藏编辑器按钮默认布局 /数据选择器dataPicker / entityTypesdataPickerEmbeddingDataPicker见 EmbeddingDataPicker.md控制问题中数据源选择菜单的形态取值为staged | flat。文档特别提示设置为dataPicker staged可获得完整的数据选择器分步式选择体验。entityTypesEmbeddingEntityType[]见 EmbeddingEntityType.md声明数据选择器中可用的实体类型数组取值为model | table | question即模型、数据表与已保存问题。InteractiveQuestion questionIdnew dataPickerstaged entityTypes{[table, model, question]} /布局样式height / width / className / styleheight/width接受数字或字符串形式的 CSS 尺寸值类型为Heightstring | number/Widthstring | number控制组件尺寸。className追加到根元素的自定义类名。style追加到根元素的自定义内联样式对象CSSProperties。在源码实现中这些样式属性最终由SdkQuestionDefaultView透传给默认布局容器同时 drill-through 渲染renderDrillThroughQuestion也会继承 height/width/className/style保证下钻页面与主视图视觉一致。plugins向问题注入扩展能力plugins的类型为MetabasePluginsConfig见 MetabasePluginsConfig.mdtype MetabasePluginsConfig { dashboard?: MetabaseDashboardPluginsConfig; mapQuestionClickActions?: MetabaseClickActionPluginsConfig; };即通过mapQuestionClickActions为地图类问题的点击行为注入自定义操作。在源码中plugins会被转发为SdkQuestionProvider的componentPlugins是整个问题上下文context的一部分因此所有子组件Filter、Summarize、Editor 等都能感知到插件的存在。从源码看默认值与内部流转在 SdkQuestion.tsx 的_SdkQuestion实现中可以确认以下运行时默认值与文档语义完全一致属性源码默认值isSaveEnabledtruewithDownloadsfalsewithAlertsfalsewithChartTypeSelectortruewithEditorButtontrue内部流转上SdkQuestion将除展示层外的所有业务属性透传给SdkQuestionProvider问题上下文子组件通过 context 读取当未传入children时默认渲染SdkQuestionDefaultView作为默认布局。值得注意的是源码注释表明initialVisualization当前在公开边界被禁用内部管线保留这意味着该能力属于内部预留而非当前公开 API。另外InteractiveQuestion通过Object.assign将 20 余个子组件挂载为静态成员并附带schema字段interactiveQuestionSchema用于自定义布局custom layouts时按需组合Filter、Summarize、Editor、ChartTypeSelector、DownloadWidget、SaveButton等原子组件详见 InteractiveQuestionComponents.md。在自定义布局中SaveButton必须提供onClick处理器否则点击无效EditorButton同理必须配置onClick。完整属性速查表以下为SdkQuestionProps的全部 27 个属性与InteractiveQuestionProps基本一致供嵌入开发时对照查阅属性类型说明className?string添加到根元素的自定义类名dataPicker?EmbeddingDataPicker控制问题数据源选择菜单设staged使用完整数据选择器entityTypes?EmbeddingEntityType[]声明数据选择器中可用的实体类型model/table/questionheight?Heightstring \| number组件高度CSS 尺寸值hiddenParameters?string[]需要隐藏的参数列表initialCollection?SdkCollectionId保存弹窗集合选择器的预选项选择器仍可见、用户可改选设置了targetCollection时忽略initialSqlParameters?SqlParameterValuesSQL 参数初始值按 slug 键控仅挂载时应用一次值为null严格清空省略则回退默认值isSaveEnabled?boolean是否显示保存按钮onBeforeSave?(question, context) Promisevoid保存前回调仅isSaveEnabled true时相关onNavigateBack?() void用户点击返回按钮时触发onRun?(question) void问题更新时触发含点击 Visualize 按钮onSave?(question, context) void保存成功回调仅isSaveEnabled true时相关onSqlParametersChange?(payload) voidSQL 参数变更回调source区分initial-state/manual-change/auto-changeonVisualizationChange?(display) void可视化类型切换回调plugins?MetabasePluginsConfig插件配置地图点击行为等questionId?SdkQuestionId \| null问题 ID数字 ID / entity_id /new/new-nativesqlParameters?SqlParameterValues受控 SQL 参数值每次渲染整体替换与onSqlParametersChange配对使用style?CSSProperties添加到根元素的自定义内联样式targetCollection?SdkCollectionId保存问题的目标集合隐藏保存弹窗的集合选择器仅交互式问题适用title?SdkQuestionTitleProps是否显示标题及自定义标题false隐藏默认显示token?string \| null用于 guest embed 的有效 JWT tokenwidth?Widthstring \| number组件宽度CSS 尺寸值withAlerts?boolean启用问题告警设置能力withChartTypeSelector?boolean是否显示图表类型选择器及设置按钮仅默认布局withDownloads?boolean启用问题结果下载withEditorButton?boolean是否显示编辑器按钮仅默认布局配合InteractiveQuestion、StaticQuestion等公开组件以及SdkQuestionEntityPublicProps的互斥约束你可以在不触碰 Metabase 后端的情况下用这组 Props 构建出从只读展示到全功能自助分析的嵌入体验。【免费下载链接】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），仅供参考