Metabase Embedding SDK ChartColor 类型解析图表配色主题的 base / tint / shade 定制指南【免费下载链接】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/metabaseChartColor 是 Metabase Embedding SDK 中用于自定义嵌入式图表配色的核心类型定义允许开发者以纯字符串或包含base/tint/shade三色变体的对象形式为嵌入应用中的图表系列指定颜色。本指南围绕该类型的完整结构、在 SDK 主题配置中的实际位置、底层实现原理与实战示例展开帮助你掌握如何将品牌色体系精确映射到嵌入式 Metabase 图表上。类型定义一览ChartColor 是一个联合类型union type其官方定义为见 docs/embedding/sdk/api/snippets/ChartColor.mdtype ChartColor | string | { base: string; shade?: string; tint?: string; };在仓库源码中的完整定义位于 frontend/src/metabase-types/api/embedding-theme.ts与文档保持一致export type ChartColor | string | { base: string; /** Lighter variation of the base color */ tint?: string; /** Darker variation of the base color */ shade?: string; };可以看到该类型有两种合法形态纯字符串直接给出一组图表色值例如#509EE3此时 SDK 会根据该颜色自动推导出对应的浅色tint与深色shade变体对象形态显式声明base并可选地覆盖tint更亮的变体与shade更暗的变体。字段说明NameTypeDescriptionbasestring图表系列的基准色必填shade?string基准色的深色变体Darker variation of the base colortint?string基准色的浅色变体Lighter variation of the base color其中base为必填项tint与shade均为可选。从 SDK 主题类型 frontend/src/metabase-types/api/embedding-theme.ts 可以看到ChartColor 数组被挂在主题对象的charts字段上/** Chart colors */ charts?: ChartColor[];即在一个MetabaseTheme或MetabaseColors对象中通过charts数组按顺序为图表系列指定颜色数组中的每个元素就是上述联合类型的一个值。源码级实现tint / shade 的推导与映射从 ChartColor 数组到 accent 色板在 SDK 主题初始化时charts数组并不会被直接使用而是经过 mapChartColorsToAccents 函数转换为 Metabase 内部的 accent 系列颜色accent0~accent7与accent-gray以及各自的-light/-dark变体。其转换规则如下纯字符串映射为对应索引的accent{index}基准色并自动推导accent{index}-light与accent{index}-dark对象形态base映射为accent{index}tint/shade若提供则直接映射为accent{index}-light/accent{index}-dark否则同样由base推导。索引到 accent 键名的完整映射表定义在 frontend/src/metabase/ui/colors/constants/accents.tsexport const ACCENT_COLOR_NAMES_MAP [ { base: accent0, tint: accent0-light, shade: accent0-dark }, { base: accent1, tint: accent1-light, shade: accent1-dark }, // ... 直到 accent7 { base: accent-gray, tint: accent-gray-light, shade: accent-gray-dark }, ] as const satisfies ChartColorV2[];tint / shade 的自动推导公式当只提供base或以纯字符串形式时SDK 依据 deriveChartTintColor 与 deriveChartShadeColor 自动生成变体tint将基准色亮度提升CHART_TINT_SHADE_FACTOR即 0.125见 frontend/src/metabase/ui/colors/constants/accents.ts后取十六进制色值shade将基准色亮度降低同样的 0.125 因子。也就是说如果你没有显式指定tint/shadeMetabase 会以“亮度加减 12.5%”的算法从base推导出完整的一组浅色/深色变体保证图表的 hover、渐变等场景始终有协调的配色。全局色板的注入推导完成后的 accent 色值会通过 getEmbeddingColorPalette 与 setGlobalEmbeddingColors 合并进全局颜色对象最终以var(--mb-color-...)CSS 变量的形式驱动嵌入页面中所有可视化组件。这也是 ChartColor 配置能即刻生效、覆盖图表的底层机制。默认图表色板仓库内置的默认图表色板frontend/src/metabase/ui/colors/constants/accent-colors.ts以纯字符串形式定义可作为 ChartColor 数组的参考范式export const DEFAULT_ACCENT_COLORS: ChartColorV2[] [ #509EE3, // accent0 - blue #88BF4D, // accent1 - green #A989C5, // accent2 - purple #EF8C8C, // accent3 - red #F9D45C, // accent4 - yellow #F2A86F, // accent5 - orange #98D9D9, // accent6 - cyan #7172AD, // accent7 - indigo ];浅色主题与深色主题还会在默认 8 色基础上追加一个采用对象形态定义的灰色系分别为baseColors.orion[10]/orion[80]等明暗不同的中性色证明对象形态与字符串形态可以在同一数组中混用。实战示例纯字符串快速覆盖图表配色当你的品牌主色恰好能对应一套现成色板时直接传字符串数组即可const theme: MetabaseTheme { colors: { brand: #FF7A45, // ... 其他主题色 }, charts: [ #509EE3, #88BF4D, #A989C5, #EF8C8C, #F9D45C, #F2A86F, #98D9D9, #7172AD, ], };此时 SDK 会自动为每一色推导-light/-dark变体无需手动维护衍生色。对象形态精确控制每个系列的明暗变体当 hover 或数据高亮需要完全可控的明暗色时使用对象形态const theme: MetabaseTheme { charts: [ { base: #1F6FEB, // 品牌蓝 tint: #58A6FF, // 浅色变体浅蓝 shade: #1158C7, // 深色变体深蓝 }, #88BF4D, // 第二个系列可以继续混用字符串 // ... ], };这样图表在普通状态、浅色强调状态与深色强调状态下都能严格使用你指定的色值而不是依赖推导结果。与组件级主题搭配使用ChartColor 数组属于顶层主题的charts字段可与其他colors如brand、positive、negative以及MetabaseComponentTheme的组件级配置如 dashboard 卡片、tooltip 颜色等同时传入同一个MetabaseTheme对象共同作用于嵌入应用。关键注意事项charts数组中位置即索引第 1 个元素对应accent0以此类推超出第 9 个位置accent-gray的元素在转换时会被截断忽略见 frontend/src/metabase/ui/colors/accents.ts 的slice(0, 9)数组元素允许为null用于跳过某个位置的配色而不改变后续索引见 frontend/src/metabase/ui/colors/types/theme.ts 的ChartColorV2定义tint与shade均未提供时SDK 使用 0.125 亮度因子自动推导提供的任意一个都会覆盖对应方向的推导结果该类型定义同时被 Embedding SDK 公开 APIfrontend/src/metabase/embedding-sdk/theme/MetabaseTheme.ts 重新导出与内部 V2 主题体系ChartColorV2见 frontend/src/metabase/ui/colors/types/theme.ts复用是贯穿主题配置的核心类型之一。通过理解 ChartColor 的联合类型结构与base/tint/shade的推导规则你可以在嵌入式应用中用最少的配置实现一套与品牌完全对齐的图表配色体系。【免费下载链接】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），仅供参考
