Metabase Embedding SDK 组件级主题定制MetabaseComponentTheme 完整指南【免费下载链接】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导读MetabaseComponentTheme是 Metabase React Embedding SDK 中用于按组件维度精细定制嵌入外观的主题类型它不修改全局色板而是直接作用于图表、数据表、仪表盘、透视表、悬浮提示等具体组件的字号、颜色、内边距与层级。本文以该类型的官方 API 文档为主体结合仓库中MetabaseComponentTheme的类型定义、默认主题实现与官方使用指南完整拆解其全部属性、默认取值与源码实现原理读完即可在你的嵌入应用中写出一套精细到单元格字号的组件级主题。MetabaseComponentTheme 是什么MetabaseComponentTheme是 Metabase Embedding SDK 暴露的 TypeScript 类型用于自定义特定 Metabase 组件与可视化的主题选项Theme options for customizing specific Metabase components and visualizations。它与MetabaseTheme的关系是在 MetabaseTheme 接口 中组件级主题通过components字段接入export interface MetabaseTheme { preset?: MetabaseThemePreset; // light | dark fontSize?: string; // 基础字号支持 px、em、rem默认约 14px fontFamily?: MetabaseFontFamily; lineHeight?: string | number; colors?: MetabaseColors; // 全局色板 components?: DeepPartialMetabaseComponentTheme; // 组件级主题 }注意components的类型是DeepPartialMetabaseComponentTheme即所有字段均可选你只需覆盖想调整的层级未指定的部分自动回落到 SDK 内置默认值。在源码层面该类型定义于 embedding-theme.ts由 MetabaseTheme.ts 统一对外导出其默认实现在 default-component-theme.ts。完整类型定义以下为官方 API 文档MetabaseComponentTheme.md给出的完整类型定义共覆盖 9 大组件类别type MetabaseComponentTheme { cartesian: { goalLine: { label: { fontSize: string; }; }; label: { fontSize: string; }; padding?: string; splitLine: { lineStyle: { color: string; }; }; }; collectionBrowser: { breadcrumbs: { expandButton: { backgroundColor: {}; hoverBackgroundColor: {}; hoverTextColor: {}; textColor: {}; }; }; emptyContent: { icon: { height: CSSProperties[width]; width: CSSProperties[width]; }; subtitle: { fontSize: CSSProperties[fontSize]; }; title: { fontSize: CSSProperties[fontSize]; }; }; }; dashboard: { backgroundColor: string; card: { backgroundColor: string; border?: string; }; gridBorderColor?: string; }; number?: { value?: { fontSize?: CSSProperties[fontSize]; lineHeight?: string; }; }; pivotTable: { cell: { fontSize: string; }; rowToggle: { backgroundColor: string; textColor: string; }; }; popover: { zIndex?: number; }; question: { backgroundColor: string; toolbar?: { backgroundColor?: string; }; }; table: { cell: { backgroundColor?: string; fontSize: string; textColor: string; }; idColumn?: { backgroundColor?: string; textColor: string; }; stickyBackgroundColor?: string; }; tooltip?: { backgroundColor?: string; focusedBackgroundColor?: string; secondaryTextColor?: string; textColor?: string; }; };其中CSSProperties指 React 的CSSProperties类型即React.CSSProperties取用其width、fontSize等索引签名表示这些字段与 React 内联样式的对应属性同型string | number等。带?的字段为可选其余为必填但外层整体经DeepPartial包裹后实际使用时全部可省略。属性详解cartesian笛卡尔坐标系图表用于折线图、柱状图等笛卡尔坐标系图表的文字与网格样式属性类型说明cartesianobject笛卡尔图表配置cartesian.goalLine.label.fontSizestring目标线goal line标签的字号cartesian.label.fontSizestring图表内标签的字号例如坐标轴刻度与系列名称cartesian.padding?string图表周围的内边距使用 CSSpadding格式如4px 8pxcartesian.splitLine.lineStyle.colorstring分割线网格线的颜色collectionBrowser收藏集浏览组件控制收藏集浏览器的面包屑导航与空状态展示属性类型说明collectionBrowser.breadcrumbs.expandButton.backgroundColorCSSProperties面包屑展开按钮背景色collectionBrowser.breadcrumbs.expandButton.hoverBackgroundColorCSSProperties按钮悬停背景色collectionBrowser.breadcrumbs.expandButton.hoverTextColorCSSProperties按钮悬停文字色collectionBrowser.breadcrumbs.expandButton.textColorCSSProperties按钮文字色collectionBrowser.emptyContent.icon.heightCSSProperties[width]空状态图标高度collectionBrowser.emptyContent.icon.widthCSSProperties[width]空状态图标宽度collectionBrowser.emptyContent.subtitle.fontSizeCSSProperties[fontSize]空状态副标题字号collectionBrowser.emptyContent.title.fontSizeCSSProperties[fontSize]空状态标题字号dashboard仪表盘控制仪表盘整体与卡片外观属性类型说明dashboard.backgroundColorstring所有仪表盘的背景色dashboard.card.backgroundColorstring所有仪表盘卡片的背景色dashboard.card.border?string为卡片设置自定义边框时使用。取值与 CSSborder属性相同如1px solid #ff0000。设置后将替换卡片原有的阴影效果dashboard.gridBorderColor?string仪表盘网格的边框颜色仅在编辑仪表盘时显示。默认为colors.bordernumber数字图表属性类型说明number.value.fontSize?CSSProperties[fontSize]数字图表中数值的字号number.value.lineHeight?string数值的行高number.value同时适用于趋势图中的主数值。pivotTable透视表属性类型说明pivotTable.cell.fontSizestring单元格数值字号默认约 12pxpivotTable.rowToggle.backgroundColorstring透视表行展开/折叠按钮的背景色pivotTable.rowToggle.textColorstring透视表行展开/折叠按钮的文字色popover弹出层属性类型说明popover.zIndex?number覆盖层的 z-index。当组件被嵌入到模态框内时尤其有用。默认为 200question问题属性类型说明question.backgroundColorstring所有问题的背景色question.toolbar.backgroundColor?string默认交互式问题布局中工具栏的背景色table数据表属性类型说明table.cell.backgroundColor?string单元格默认背景色默认取background色table.cell.fontSizestring单元格数值字号默认约 12.5pxtable.cell.textColorstring单元格文字色默认取text-primarytable.idColumn.backgroundColor?stringID 列背景色默认为lighten(brand)品牌色的浅色变体table.idColumn.textColorstringID 列文字色默认取brandtable.stickyBackgroundColor?string滚动时保持固定的表头背景色。若未设置单元格背景色默认为whitetooltip悬浮提示属性类型说明tooltip.backgroundColor?string提示框背景色tooltip.focusedBackgroundColor?string聚焦行的提示框背景色tooltip.secondaryTextColor?string提示框中的次要文字颜色例如提示框标题与百分比变化tooltip.textColor?string提示框文字颜色源码中的默认值default-component-theme.tsMetabaseComponentTheme并非空壳类型仓库在 default-component-theme.ts 中提供了两套默认实现理解它们能帮助你判断不设置某项时界面会怎样。第一套DEFAULT_METABASE_COMPONENT_THEMEL33-L98为组件提供基础默认值关键取值包括export const DEFAULT_SDK_FONT_SIZE 14; // 默认基础字号 14px const FONT_SIZES { tableCell: units(12.5), // 数据表单元格 ~12.5px pivotTableCell: units(12), // 透视表单元格 ~12px label: units(13), // 笛卡尔图表标签 ~13px goalLabel: units(13), // 目标线标签 ~13px };其默认值全部使用 CSS 变量引用例如单元格文字色为var(--mb-color-text-primary)、ID 列文字色为var(--mb-color-core-brand)、分割线颜色为var(--mb-color-cartesian-grid-line)并设置了popover.zIndex OVERLAY_Z_INDEX。第二套DEFAULT_EMBEDDED_COMPONENT_THEMEL104-L134在基础默认之上针对嵌入 SDK 环境做了优化覆盖字号改用 em 单位SDK 注释明确指出Use em units to scale font sizes relative to the base font size. The em unit is used by default in the embedding SDK——即以 14px 为基准换算让所有字号随MetabaseTheme.fontSize的调整而等比缩放例如 12.5px 对应0.892857em新增cartesian.padding: 0.5rem 1rem为嵌入环境中的笛卡尔图表补充默认内边距覆盖collectionBrowser展开按钮默认背景改为transparent悬停时文字色反白、背景色使用品牌色var(--mb-color-core-brand)。由此可见官方文档表格中标注的默认约 12px / 12.5px / 13px均直接来源于此处的FONT_SIZES常量popover.zIndex默认 200 则定义于 component-theme.ts 的OVERLAY_Z_INDEX 200。如何在嵌入应用中使用组件级主题通过MetabaseProvider的theme属性注入。官方使用指南appearance.md给出了完整的components配置示例以下为综合了各组件类别的精简可运行版本import { MetabaseProvider, defineMetabaseTheme, } from metabase/embedding-sdk-react; const theme defineMetabaseTheme({ components: { dashboard: { backgroundColor: #2F3640, gridBorderColor: #EEECEC, card: { backgroundColor: #2D2D30, border: 1px solid #EEECEC, }, }, question: { backgroundColor: #2E353B, toolbar: { backgroundColor: #F3F5F7, }, }, tooltip: { textColor: #FFFFFF, secondaryTextColor: #949AAB, backgroundColor: #2E353B, focusedBackgroundColor: #0A0E10, }, table: { cell: { textColor: #4C5773, backgroundColor: #FFFFFF, fontSize: 12.5px, }, idColumn: { textColor: #9B5966, backgroundColor: #F5E9EB, }, }, number: { value: { fontSize: 24px, lineHeight: 21px, }, }, cartesian: { padding: 4px 8px, }, pivotTable: { cell: { fontSize: 12px, }, rowToggle: { textColor: #FFFFFF, backgroundColor: #95A5A6, }, }, collectionBrowser: { breadcrumbs: { expandButton: { textColor: #8118F4, backgroundColor: #767D7C, hoverTextColor: #CE8C8C, hoverBackgroundColor: #69264B, }, }, }, popover: { zIndex: 200, }, }, }); export function App() { return ( MetabaseProvider authConfig{authConfig} theme{theme} {/* 你的应用 */} /MetabaseProvider ); }常见坑位弹层被遮挡时调整 zIndex官方指南专门提醒appearance.md如果你的应用自己渲染了高 z-index 的模态框、抽屉或遮罩层SDK 内部的覆盖层如保存对话框可能被遮挡。由于 SDK 默认popover.zIndex: 200低于很多应用的自定义遮罩此时只需通过defineMetabaseTheme调高即可例如你的模态框在 1000则设为 1001const theme defineMetabaseTheme({ components: { //... 其他主题设置 popover: { zIndex: 1001, // 高于你的遮罩层级 }, }, });该默认值 200 的来源同样可追溯至源码常量OVERLAY_Z_INDEX 200component-theme.ts。使用限制与注意事项官方文档明确了两点限制appearance.mdCSS 变量暂不支持MetabaseComponentTheme的取值应使用具体的颜色/尺寸值不能传入var(--xxx)形式的 CSS 变量可视化设置优先在问题Question的可视化设置中显式设置的图表颜色会覆盖主题中对应的颜色。此外建议遵循以下实践善用DeepPartialMetabaseTheme.components是深度可选类型按需覆盖最小层级即可未覆盖项自动使用 default-component-theme.ts 中的默认值统一用主题字号在嵌入环境中fontSize类字段建议传 em 单位或依赖默认换算使整体字号能随MetabaseTheme.fontSize基准联动保持品牌一致性table.idColumn、collectionBrowser悬停态等字段默认与brand品牌色绑定手动覆盖时注意与全局colors色板协调。源码索引类型定义embedding-theme.tsMetabaseTheme、MetabaseColors、MetabaseComponentTheme对外导出MetabaseTheme.ts默认值实现default-component-theme.ts弹出层常量component-theme.tsOVERLAY_Z_INDEX 200官方使用指南appearance.mdAPI 索引snippets/index.md【免费下载链接】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），仅供参考