Metabase Embedded Analytics SDK 的 SdkQuestionTitleProps 类型详解控制与自定义问题标题【免费下载链接】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导读SdkQuestionTitleProps是 Metabase Embedded Analytics SDK 中用于控制“问题Question标题”显示方式的核心类型别名。它定义在 frontend/src/embedding-sdk-bundle/types/question.ts并被InteractiveQuestion、StaticQuestion、CreateQuestion、EditableDashboard等多个 SDK 组件共用的title?属性引用。本篇文章将带你完整掌握该类型的四种合法取值形态、各自的渲染行为与优先级、在实际嵌入场景中的使用方式并结合仓库源码与单元测试逐层印证其底层实现。类型定义一个属性四种形态关联文档 SdkQuestionTitleProps.md 给出了该类型的精确定义type SdkQuestionTitleProps | boolean | undefined | ReactNode | () ReactNode;从源码 question.ts 中可以确认这与 SDK 内部embedding-sdk-bundle包中导出的类型完全一致其注释还保留了一条待办事项未来会将该函数形态改为接收question: Question参数对应内部 issue metabase#50487目前函数调用时不传入任何参数。这四种形态分别代表四种使用场景取值形态语义典型用途booleantrue/false显式控制标题是否显示隐藏标题或强制显示默认标题undefined不传该属性走默认行为大多数场景保持 SDK 默认外观ReactNode用任意 React 节点替换默认标题传入字符串、h1等 JSX 元素实现自定义标题() ReactNode用渲染函数动态生成标题根据运行状态计算标题内容属性来源哪些组件接受该类型SdkQuestionTitleProps是一个“共享的公共属性类型”。在 SDK 的 API 文档中它出现在多个组件的title?属性上例如InteractiveQuestionProps.mdtitle?的类型即为SdkQuestionTitleProps说明是Determines whether the question title is displayed, and allows a custom title to be displayed instead of the default question title. Shown by default.决定问题标题是否显示并允许用自定义标题替代默认标题默认显示。SdkQuestionProps.mdCreateQuestionProps.mdStaticQuestionProps.mdDrillThroughQuestionProps.mdEditableDashboardProps.md 中同样出现也就是说只要是在 SDK 中渲染单个问题Question视图的组件几乎都会透传这个title?属性其行为语义是一致的控制标题显隐或自定义标题内容。在内部实现上SdkQuestionDefaultView.tsx 的SdkQuestionDefaultViewProps接口也定义了同名的title?: SdkQuestionTitleProps属性并被实际渲染在顶部工具栏区域SdkQuestionDefaultView.tsx。渲染原理DefaultViewTitle 的分支逻辑标题最终由 DefaultViewTitle.tsx 组件负责渲染。从源码结构看它依据title的值走完全不同的分支title false直接返回null即彻底隐藏标题DefaultViewTitle.tsx。title undefined或title true调用getQuestionTitle(question, tc)从问题对象中取出默认标题文本若取不到null则同样不渲染否则渲染为加粗大号Textfw{700}、fzxl颜色使用主题变量--mb-color-text-primaryDefaultViewTitle.tsx。title为字符串将该字符串通过useTranslateContent的tc()做内容翻译后渲染为标题文本DefaultViewTitle.tsx。title为函数将其视为组件直接调用CustomTitle /渲染函数返回值即标题内容DefaultViewTitle.tsx。其他情况如 React 元素原样渲染该节点DefaultViewTitle.tsx。由此可以推断出完整的决策优先级false优先于一切之后才是undefined/true的默认标题、字符串、函数与任意 React 节点。使用示例四种形态全覆盖以下示例均基于 SDK 的InteractiveQuestion组件同样适用于StaticQuestion、CreateQuestion等假设你的应用已按 quickstart.md 完成 SDK 初始化。1. 默认行为不传 title不传title属性时组件显示问题本身的默认标题import { InteractiveQuestion } from metabase/embedding-sdk-react; export const DefaultTitle () { return InteractiveQuestion questionId{1} /; };2. 隐藏标题title{false}export const HideTitle () { return InteractiveQuestion questionId{1} title{false} /; };适合标题信息冗余、希望最大化可视化区域空间的场景。3. 使用字符串自定义标题export const CustomTitleText () { return InteractiveQuestion questionId{1} title2024 年度销售分析 /; };此时标题被固定为你提供的文案且字符串会经过useTranslateContent处理在启用了内容翻译的环境下会显示对应的翻译文本。4. 使用 React 元素自定义标题export const CustomTitleElement () { return ( InteractiveQuestion questionId{1} title{ div style{{ display: flex, alignItems: center, gap: 8px }} span/span h1 style{{ margin: 0 }}销售驾驶舱/h1 /div } / ); };React 节点形态让开发者可以完全掌控标题的 DOM 结构与样式突破默认标题的样式限制。5. 使用渲染函数动态生成标题export const DynamicTitle () { const userName Alice; return ( InteractiveQuestion questionId{1} title{() h2{userName} 的个性化报表/h2} / ); };函数形态每次渲染都会重新调用适合需要根据上下文如当前用户、日期、权限等动态计算标题内容的场景。需要注意按照当前源码实现该函数被调用时不会传入question参数见 question.ts 中的 TODO 注释如需读取问题信息需通过其他途径获取。单元测试行为即规格SDK 的单元测试文件 SdkQuestion.unit.spec.tsx 用一张参数化用例表完整覆盖了title属性的所有形态SdkQuestion.unit.spec.tsxit.each([ // shows the question title by default [undefined, My Question], // hides the question title when title{false} [false, null], // shows the default question title when title{true} [true, My Question], // customizes the question title via strings [Foo Bar, Foo Bar], // customizes the question title via React elements [h1 keyfooFoo Bar/h1, Foo Bar], // customizes the question title via React components. [() h1Foo Bar/h1, Foo Bar], ])( shows the question title according to the title prop, async (titleProp, expectedTitle) { await setup({ title: titleProp }); const element screen.queryByText(expectedTitle ?? My Question); expect(element?.textContent ?? null).toBe(expectedTitle); }, );这些用例验证的行为可以总结为一张事实对照表传入的title值页面呈现的标题依据undefined不传问题的默认标题如 My Question默认显示false无标题隐藏true问题的默认标题强制显示Foo Bar字符串文本 Foo Bar自定义字符串h1Foo Bar/h1React 元素元素内容 Foo Bar自定义节点() h1Foo Bar/h1函数函数返回的元素内容自定义渲染函数测试同时通过screen.queryByText断言了标题的显示/隐藏状态这意味着标题的行为完全由title属性驱动与SdkQuestionDefaultView中RenderIfHasContent的布局逻辑配合空标题时顶部工具栏会自动收缩不会残留空白区域。与自定义布局Custom Layout配合使用SDK 支持通过 children 自定义InteractiveQuestion的内部布局。在 SdkQuestion.unit.spec.tsx 中可以看这样一个自定义布局示例function InteractiveQuestionCustomLayout({ title }: { title?: SdkQuestionTitleProps }) { const { resetQuestion } useSdkQuestionContext(); return ( div button onClick{resetQuestion}Run Query/button SdkQuestionDefaultView title{title} / /div ); }title属性由外层传入、透传给SdkQuestionDefaultView最终由DefaultViewTitle消费。也就是说无论你是否使用默认布局title的四种形态语义都保持一致。开发者也可以完全不使用默认视图而在自己的布局中直接渲染自定义标题元素。小结SdkQuestionTitleProps虽是一个仅四行的类型别名却承担了 Metabase Embedded Analytics SDK 中问题标题的全部控制逻辑boolean/undefined控制标题的显隐与默认行为ReactNode支持任意自定义标题内容字符串、JSX 元素() ReactNode支持动态计算标题。通过阅读 DefaultViewTitle.tsx 的分支实现与 SdkQuestion.unit.spec.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），仅供参考