Metabase Embedding SDK ChartColor 类型解析：图表配色主题的 base / tint / shade 定制指南

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/metabase

ChartColor 是 Metabase Embedding SDK 中用于自定义嵌入式图表配色的核心类型定义，允许开发者以纯字符串或包含base/tint/shade三色变体的对象形式，为嵌入应用中的图表系列指定颜色。本指南围绕该类型的完整结构、在 SDK 主题配置中的实际位置、底层实现原理与实战示例展开，帮助你掌握如何将品牌色体系精确映射到嵌入式 Metabase 图表上。

类型定义一览

ChartColor 是一个联合类型（union type），其官方定义为（见 docs/embedding/sdk/api/snippets/ChartColor.md）：

type 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; };

可以看到该类型有两种合法形态：

1. 纯字符串：直接给出一组图表色值，例如"#509EE3"，此时 SDK 会根据该颜色自动推导出对应的浅色（tint）与深色（shade）变体；
2. 对象形态：显式声明base，并可选地覆盖tint（更亮的变体）与shade（更暗的变体）。

字段说明

Name	Type	Description
base	string	图表系列的基准色，必填
shade?	string	基准色的深色变体（Darker variation of the base color）
tint?	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.ts：

export 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/shade，Metabase 会以“亮度加减 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 公开 API（frontend/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