Metabase Embedding SDKInteractiveQuestion组件 API 全解析从默认布局到自定义组合【免费下载链接】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导读InteractiveQuestion是 Metabase Embedding SDK 中最具开放性的嵌入式组件它不仅渲染一个可交互的问题Question更将问题编辑器拆解为 20 个可独立使用的子组件过滤、汇总、分组、图表类型、可视化、保存等让你在 React 应用中完全掌控提问—编辑—可视化—保存的完整链路。本文以官方 API 文档 InteractiveQuestionComponents.md 为骨架结合仓库源码逐一对齐每个子组件的签名、参数与行为并给出自定义布局与默认布局的实践路径。一、InteractiveQuestion是什么一个组件一套命名空间InteractiveQuestion在 SDK 中同时承担两种角色一个函数组件接收 InteractiveQuestionProps渲染一个完整可用的交互式问题含工具栏、可视化与编辑能力。一组命名空间子组件通过InteractiveQuestion.Filter、InteractiveQuestion.Editor这类点语法访问用于在自定义布局中按需组装 UI。从源码看这个双重身份是显式构造出来的。InteractiveQuestion.tsx 中InteractiveQuestion通过Object.assign将 20 个子组件挂载到函数组件本体上同时挂载schema用于 Storybook 等场景的 schema 描述再包一层withPublicComponentWrappersupportsGuestEmbed: false即该组件不面向 Guest 匿名嵌入。组件内部只是把card/query反序列化后透传给底层 SdkQuestion.tsx真正的问题加载、执行与上下文管理由SdkQuestionProvider提供。import { InteractiveQuestion } from metabase/embedding-sdk-react; // 默认布局开箱即用 InteractiveQuestion questionId{42} /; // 自定义布局用命名空间子组件自由组合 InteractiveQuestion questionId{42} InteractiveQuestion.Title / InteractiveQuestion.Filter / InteractiveQuestion.Summarize / InteractiveQuestion.QuestionVisualization / /InteractiveQuestion;注意源码中SdkQuestion的withDownloads与withAlerts默认值均为false见 SdkQuestion.tsx需要下载与预警能力时请显式开启。二、编辑与保存类组件Editor、EditorButton、SaveButton、SaveQuestionForm这一组组件覆盖修改问题定义与落库保存两个环节是自定义分析工作流的核心。Editor()原Notebook()已弃用Editor: (props: InteractiveQuestionEditorProps) Element | null;高级查询编辑器提供对问题配置的完整访问包括过滤filtering聚合aggregation自定义表达式custom expressions表连接joinsNotebook()与NotebookButton()已被标记弃用官方明确要求改用InteractiveQuestion.Editor/EditorButton。在源码 SdkQuestion.tsx 中Notebook与Editor指向同一个Editor实现NotebookButton与EditorButton同样同源保证向后兼容。EditorButton()EditorButton: (props: InteractiveQuestionEditorButtonProps) Element | null;用于显示/隐藏Editor的切换按钮。官方文档特别强调了一个关键约束在自定义布局中EditorButton必须提供 InteractiveQuestionEditorButtonProps.onClick 处理器否则点击按钮不会有任何效果。这是因为 SDK 不会替你在自定义布局里自动接线onClick需要由宿主应用自己实现通常是切换编辑器显隐的 state这与默认布局中 SDK 内部自动管理编辑器开关的行为不同。SaveButton()SaveButton: (props?: InteractiveQuestionSaveButtonProps) Element;保存问题修改的按钮仅当问题存在未保存的修改时处于可用状态。文档同时给出一个注意事项在当前版本的自定义布局中SaveButton同样必须提供onClick处理器否则点击无效。默认布局中 SDK 已接线无需额外处理。SaveQuestionForm()SaveQuestionForm: (props: InteractiveQuestionSaveQuestionFormProps) Element | null;保存问题的表单包含标题title与描述description。保存时的行为文档明确列出的三条对已存在的问题调用 SdkQuestionProps.onSave两类回调新问题与已有问题都会收到更新后的问题对象表单可通过 InteractiveQuestionSaveQuestionFormProps.onCancel 取消配合 InteractiveQuestionProps 中的isSaveEnabled是否显示保存按钮、onBeforeSave保存前回调可做校验/拦截、onSave保存成功回调可以完整接管保存链路。三、数据探索类组件Filter、Summarize、Breakout 与下拉变体这组组件负责从数据中提炼信息的三种基本操作过滤、汇总、分组。Filter()与FilterDropdown()Filter: (props: InteractiveQuestionFilterProps) Element; FilterDropdown: (props: InteractiveQuestionFilterDropdownProps) Element | null;Filter渲染一组交互式过滤徽章badges支持添加、编辑、移除过滤器当前过滤器以徽章形式展示并提供Add another filter添加另一个过滤器入口。FilterDropdown是Filter的下拉按钮形态适合工具栏空间有限的布局。Summarize()与SummarizeDropdown()Summarize: () Element; SummarizeDropdown: (props: InteractiveQuestionSummarizeDropdownProps) Element | null;Summarize提供添加与管理数据汇总如计数 count、求和 sum、平均值 average的界面同样以一组徽章呈现文档说明其使用问题上下文question context实现汇总功能。SummarizeDropdown是它的下拉按钮形态。Breakout()与BreakoutDropdown()Breakout: () Element | null; BreakoutDropdown: (props: InteractiveQuestionBreakoutDropdownProps) Element | null;Breakout是管理数据分组groupings / breakouts的徽章组例如按月份或地区分组后再看指标。BreakoutDropdown是其下拉按钮形态。三者共享问题上下文因此对某个组件的操作会即时反映到其余组件与可视化上。四、可视化类组件QuestionVisualization、ChartTypeDropdown、ChartTypeSelector、QuestionSettings这一组决定了数据最终以什么形态呈现。QuestionVisualization()QuestionVisualization: (props: { className?: string; style?: CSSProperties; } { height?: Heightstring | number; width?: Widthstring | number; } {}) Element;主可视化组件将问题结果渲染为图表、表格或其他可视化类型。参数分两层className/style挂到根元素上的自定义类名与样式对象height/widthCSS 尺寸值数字或字符串用于控制组件宽高ChartTypeDropdown()与ChartTypeSelector()ChartTypeDropdown: (props: InteractiveQuestionChartTypeDropdownProps) Element; ChartTypeSelector: (props: StackProps) Element;ChartTypeDropdown选择可视化类型的下拉框柱状图 bar、折线图 line、表格 table 等文档明确它会根据当前数据自动更新为推荐的可视化类型。ChartTypeSelector更详细的图表类型选择界面同样带推荐选项。其props类型为 Mantine 的StackPropsMantine v7 的 Stack 布局属性。QuestionSettings()与QuestionSettingsDropdown()QuestionSettings: (props: StackProps) Element | null; QuestionSettingsDropdown: (props?: InteractiveQuestionQuestionSettingsDropdownProps) Element;QuestionSettings是配置可视化选项的设置面板覆盖坐标轴axes、颜色colors、格式formatting等文档同样说明其使用问题上下文。QuestionSettingsDropdown是包含QuestionSettings的下拉按钮注意它的props是可选参数。ResetButton()ResetButton: (props?: ButtonProps) Element | null;重置问题修改的按钮仅在存在未保存的修改时出现与SaveButton的可用态逻辑互补。props类型为 ButtonProps可选。五、结果输出与下载类组件DownloadWidget、DownloadWidgetDropdown、VisualizationButtonDownloadWidget()与DownloadWidgetDropdown()DownloadWidget: (props: StackProps) Element | null; DownloadWidgetDropdown: (props: PopoverProps) Element | null;DownloadWidget提供数据下载 UI支持格式依可视化类型而定CSV、XLSX、JSON以及PNG图片导出仅对部分图表有效。DownloadWidgetDropdown是一个按钮点击后弹出的 Popover 中展示DownloadWidget其props类型为 Mantine 的PopoverProps。VisualizationButton()VisualizationButton: () Element | null;触发可视化动作的按钮——即运行当前问题并渲染结果。在InteractiveQuestionProps.onRun的文档说明中提到当问题被更新包括用户点击编辑器中的 Visualize 按钮时会触发onRun回调与这里的VisualizationButton行为对应。六、信息与导航类组件Title、BackButton、NavigationBackButton、AlertsButton、SqlParametersListTitle()Title: (props: { className?: string; style?: CSSProperties }) Element | undefined;根据问题状态显示标题问题已保存显示问题的显示名称display name临时问题ad-hoc非原生 SQL 查询显示自动生成的描述文本className与style均为可选用于定制根元素样式。BackButton()已弃用与NavigationBackButton()BackButton: (props: InteractiveQuestionBackButtonProps) Element | null; // deprecated NavigationBackButton: (props: { className?: string; style?: CSSProperties }) ReactNode;BackButton是返回上一视图的导航按钮仅在 InteractiveDashboardProps.renderDrillThroughQuestion 渲染的钻取问题drill-through question中可见。它已被标记弃用官方建议改用NavigationBackButton。NavigationBackButton是钻取与内部导航后的返回按钮当没有可返回的历史时会渲染null。源码中该按钮指向SdkInternalNavigationBackButton见 InteractiveQuestion.tsx与 SDK 内部的导航状态机集成。AlertsButton()与SqlParametersList()AlertsButton: () Element; SqlParametersList: () Element | null;AlertsButton开启/管理问题预警alerts的入口需配合InteractiveQuestionProps.withAlerts使用。SqlParametersListSQL 问题的参数列表用于展示与编辑原生查询中的变量参数。该组件与InteractiveQuestionProps.initialSqlParameters/sqlParameters/onSqlParametersChange一组受控参数配合使用sqlParameters是受控值每次渲染都会替换问题参数值onSqlParametersChange的 payload 通过source区分初始状态initial-state、用户手动修改manual-change与自动更新auto-change。七、组件 API 速查表组件签名要点关键行为/约束BackButton弃用(props) Element \| null钻取问题中返回上一视图改用NavigationBackButtonNavigationBackButton(props) ReactNode钻取/内部导航后返回无历史时渲染nullFilter(props) Element过滤徽章组可增删改过滤器FilterDropdown(props) Element \| nullFilter的下拉按钮形态Summarize() Element汇总徽章组计数/求和/平均等SummarizeDropdown(props) Element \| nullSummarize的下拉按钮形态Breakout() Element \| null分组徽章组BreakoutDropdown(props) Element \| nullBreakout的下拉按钮形态Editor原Notebook弃用(props) Element \| null高级查询编辑器过滤/聚合/表达式/连接EditorButton原NotebookButton弃用(props) Element \| null自定义布局中必须传onClickQuestionVisualization(props) Element渲染结果图表/表格支持className/style/height/widthVisualizationButton() Element \| null触发问题运行与可视化ChartTypeDropdown(props) Element图表类型下拉自动推荐ChartTypeSelector(props: StackProps) Element详细图表类型选择界面QuestionSettings(props: StackProps) Element \| null坐标轴/颜色/格式等可视化设置面板QuestionSettingsDropdown(props?) Element包含QuestionSettings的下拉按钮ResetButton(props?) Element \| null有未保存修改时才出现SaveButton(props?) Element有未保存修改才可用自定义布局中必须传onClickSaveQuestionForm(props) Element \| null保存表单触发onSave支持onCancelDownloadWidget(props: StackProps) Element \| null下载CSV/XLSX/JSON/PNGDownloadWidgetDropdown(props: PopoverProps) Element \| null含DownloadWidget的下拉按钮AlertsButton() Element预警入口需配合withAlertsSqlParametersList() Element \| nullSQL 问题参数列表八、默认布局与自定义布局的取舍从源码与文档可以提炼出两种使用模式注意以下属于对官方文档与源码结构的归纳具体取舍以你的产品场景为准默认布局开箱即用直接渲染InteractiveQuestion questionId{...} /SDK 会通过 SdkQuestionDefaultView.tsx 组装一套完整界面。此时部分行为是 SDK 自动接线的例如EditorButton无需手动onClick。自定义布局children 组合通过命名空间子组件自行编排。此时需要特别注意文档标注的手动接线要求EditorButton与SaveButton都必须提供onClick处理器同时可配合InteractiveQuestionProps上的withChartTypeSelector是否显示图表类型选择器与设置按钮仅默认布局生效、withEditorButton是否显示编辑器按钮仅默认布局生效、withDownloads是否允许下载结果等开关微调行为。对于需要把问答式探索能力嵌入自身产品的场景官方相关文档docs/embedding/sdk 目录还提供了StaticQuestion静态只读问题见 StaticQuestionComponents.md作为对照——InteractiveQuestion面向需要完整编辑能力的场景而StaticQuestion面向仅展示结果的场景二者对应不同的开放层级。九、延伸阅读InteractiveQuestionPropsquestionId、card、query、onSave、onRun、sqlParameters等全部属性InteractiveQuestion.mdInteractiveQuestion函数组件本身InteractiveDashboardPropsrenderDrillThroughQuestion钻取问题渲染入口BackButton的生效场景组件实现InteractiveQuestion.tsx、SdkQuestion.tsx、SdkQuestionDefaultView.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），仅供参考