Metabase 模块化嵌入主题配色键全解析MetabaseEmbeddingColorKeyV2 类型与保护色机制【免费下载链接】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/metabaseMetabase 的模块化嵌入Modular Embedding允许在宿主应用中通过 React SDK 深度定制嵌入组件的视觉样式。本文聚焦 SDK 主题系统中的核心类型MetabaseEmbeddingColorKeyV2——它定义了 v2 主题下可以覆写的全部颜色键Color Key白名单并借助Exclude从全量颜色键中剔除保护色与图表强调色确保嵌入方无法改动 Metabase 的品牌色、管理端配色等敏感样式。读完本文你将掌握该类型的确切取值范围、保护色机制的前端源码实现以及如何在MetabaseEmbeddingThemeV2中正确使用这些配色键。一、什么是 MetabaseEmbeddingColorKeyV2MetabaseEmbeddingColorKeyV2是 Metabase 为模块化嵌入 v2 主题单独划定的颜色键集合其完整定义位于 MetabaseEmbeddingColorKeyV2.md原始文档用两句话概括了它的职责Color keys available for theming in modular embedding这是模块化嵌入中可参与主题定制的颜色键Excludes protected colors such as admin colors that should not be exposed它排除了不应暴露给嵌入方的保护色如管理端配色。完整类型定义如下原文档全量内容一个键都不少type MetabaseEmbeddingColorKeyV2 Exclude | filter | info | warning | success | error | shadow | accent-gray | accent-gray-dark | accent-gray-light | accent0 | accent0-dark | accent0-light | accent1 | accent1-dark | accent1-light | accent2 | accent2-dark | accent2-light | accent3 | accent3-dark | accent3-light | accent4 | accent4-dark | accent4-light | accent5 | accent5-dark | accent5-light | accent6 | accent6-dark | accent6-light | accent7 | accent7-dark | accent7-light | metabase-brand | metabase-brand-hover | admin-navbar | admin-navbar-secondary | admin-navbar-inverse | upsell-primary | upsell-secondary | upsell-gem | core-metabase_brand | core-metabase_brand-hover | navbar-admin | navbar-admin-secondary | navbar-admin-inverse | background-brand | background-filter | background-disabled | background-disabled-inverse | background-error | background-error-secondary | background-highlight | background-hover | background-info | background-primary | background-primary-inverse | background-secondary | background-secondary-inverse | background-selected | background-success | background-success-secondary | background-tertiary | background-tertiary-inverse | background-warning | background-warning-secondary | border | border-strong | border-stronger | border-subtle | brand | brand-hover | danger | focus | gold | icon-brand | icon-brand-inverse | icon-disabled | icon-disabled-inverse | icon-primary | icon-primary-inverse | icon-secondary | icon-secondary-inverse | illustration-brand-secondary | illustration-brand-tertiary | overlay | saturated-blue | saturated-green | saturated-purple | saturated-red | saturated-yellow | success-secondary | summarize | syntax-parameters | syntax-parameters-active | text-hover | text-secondary-opaque | text-tertiary | text-tertiary-inverse | white | background_page-filter | background_page-highlighted | background_page-primary | background_page-primary-inverse | background_page-secondary | background_page-secondary-inverse | background_page-tertiary | background_page-tertiary-inverse | background_surface-brand-strong | background_surface-brand-strong-hover | background_surface-brand-strong-pressed | background_surface-brand-subtle | background_surface-brand-subtle-hover | background_surface-brand-subtle-pressed | background_surface-disabled | background_surface-disabled-inverse | background_surface-error | background_surface-error-subtle | background_surface-hover | background_surface-primary | background_surface-primary-hover | background_surface-primary-inverse | background_surface-primary-inverse-hover | background_surface-primary-inverse-pressed | background_surface-primary-pressed | background_surface-secondary | background_surface-secondary-hover | background_surface-secondary-inverse | background_surface-secondary-inverse-hover | background_surface-secondary-inverse-pressed | background_surface-secondary-pressed | background_surface-selected | background_surface-success | background_surface-warning | background_surface-warning-strong | border-brand | border-filter | border-highlight | border-neutral | border-neutral-strong | border-neutral-strongest | border-neutral-subtle | border-on_dark | button-label-on_dark-disabled | button-label-on_dark-primary | button-label-on_dark-secondary | button-on_dark-disabled | button-on_dark-primary-default | button-on_dark-primary-hover | button-on_dark-primary-pressed | button-on_dark-secondary-default | button-on_dark-secondary-hover | button-on_dark-secondary-pressed | core-blue-saturated | core-brand | core-brand-hover | core-filter | core-gold | core-green-saturated | core-info | core-purple-saturated | core-red-saturated | core-summarize | core-white | core-white_constant | core-yellow-saturated | feedback-negative | feedback-negative-strong | feedback-neutral-strong | feedback-positive | feedback-positive-selected | feedback-positive-strong | feedback-warning | feedback-warning-strong | illustration-secondary-brand | illustration-tertiary-brand | input-background | input-focus | modal-overlay | shadow-default | switch-checked | switch-disabled | switch-unchecked | switch_thumb-disabled | text-brand | text-brand-hover | text-brand-strong | text-brand-strong-hover | text-disabled | text-disabled-inverse | text-filter | text-primary | text-primary-inverse | text-secondary | text-secondary-inverse | text-selected | text-syntax-parameter | text-syntax-parameter-active | tooltip-background | tooltip-background-focused | tooltip-text | tooltip-text-secondary, ProtectedColorKey ;在代码层面该类型定义于 color-keys.ts同文件的MetabaseColorKey联合类型是它的父集并通过 theme.ts 从metabase/ui/colors/types统一 re-export作为 SDK 对外公开的公共类型之一。二、类型本质Exclude 从全量键中剔除了什么MetabaseEmbeddingColorKeyV2的本质是一个白名单过滤器。它并不是独立维护的一套键而是基于全量颜色键MetabaseColorKey见 MetabaseColorKey.md用 TypeScript 的Exclude...工具类型做减法得到的。被剔除的键大致可以分为三类类别被剔除的键剔除原因依据语义状态色filter、info、warning、success、error、shadow属于图表/查询层的语义色不开放给嵌入层直接覆写图表强调色accent0~accent7及其-dark/-light变体accent-gray及-dark/-light源码注释明确强调色必须通过chartColorsAPI 设置不能直接设置见下文第三节保护色ProtectedColorKey的全部成员品牌色与管理端配色不应暴露给嵌入方其余键如success-secondary、danger、background-*、border-*、text-*、icon-*、core-*、feedback-*、tooltip-*、switch-*等约 150 个键全部保留供嵌入方自由覆写。值得注意的细节剔除是精准到键的。例如success被剔除但success-secondary保留error被剔除但background-error、background_surface-error保留shadow被剔除但shadow-default、overlay、modal-overlay保留。这意味着嵌入方依然可以定制“错误态背景”“阴影容器”等外观只是不能直接改写语义主色本身。三、保护色 ProtectedColorKey哪些颜色不能被嵌入方修改ProtectedColorKey是MetabaseEmbeddingColorKeyV2中Exclude的第二个参数独立定义于 ProtectedColorKey.md共 23 个键type ProtectedColorKey | metabase-brand | metabase-brand-hover | admin-navbar | admin-navbar-secondary | admin-navbar-inverse | upsell-primary | upsell-secondary | upsell-gem | core-metabase_brand | core-metabase_brand-hover | navbar-admin | navbar-admin-secondary | navbar-admin-inverse | accent0 | accent1 | accent2 | accent3 | accent4 | accent5 | accent6 | accent7;对照运行时常量 protected-colors.ts 中的PROTECTED_COLORS数组可以看清每一组保护色的设计意图数组注释逐条写明了原因Metabase 自身品牌色metabase-brand旧名、core-metabase_brand新名——The Metabase brand color must not be modifiable品牌色是产品标识不可被嵌入方改动管理端 UI 配色admin-navbar、admin-navbar-secondary、admin-navbar-inverse旧名与navbar-admin、navbar-admin-secondary、navbar-admin-inverse新名——管理界面仅在 Metabase 自身应用中渲染不应通过嵌入暴露图表强调色accent0~accent7以及accent-gray系列——Accent colors must be set thru thechartColorsAPI, not set directly强调色必须走图表专用通道其他upsell-primary、upsell-secondary、upsell-gem等与产品内升级引导相关的配色。注意ProtectedColorKey类型定义与PROTECTED_COLORS运行时数组是两套独立维护的数据。文档中特别注明 Do not derive this fromPROTECTED_COLORSor doc generation will fail——即文档类型定义不应从常量数组机械推导否则会破坏文档生成流程。对比可见类型定义略去了accent-gray系列三个键它们由MetabaseEmbeddingColorKeyV2的Exclude列表单独剔除二者保持职责互补。保护色的过滤不仅在类型层面生效也发生在运行时。主题合并函数 derive-theme.ts 中deriveFullMetabaseTheme会先用_.omit将嵌入方传入的colors中的保护色键全部剔除再参与合并// Filter out protected colors from embedding theme overrides. // Some colors (such as the Metabase brand color) should not be modifiable. const filteredEmbeddingColors _.omit( embeddingThemeOverride?.colors, ...PROTECTED_COLORS, );也就是说即使嵌入方在运行时传入metabase-brand之类受保护的颜色键它也会在合并阶段被静默丢弃——类型约束与运行时过滤构成双重防线。四、配色键命名规范理解这 190 余个颜色键的前提是掌握 Metabase 主题令牌Token的命名规则。MetabaseColorKey的源码注释color-keys.ts给出了明确约定Token names follow[category]-[property]-[variant?]-[state?]. Parts are joined with-; when a single part is two words we join those words with_so it reads as one unit.即命名格式为[类别]-[属性]-[变体?]-[状态?]各部分用-连接当某一个部分本身由两个单词组成时用下划线_连成一个整体。例如background_surface-brand-strong类别background_surface属性brand变体strongbackground_surface-primary-inverse-hover类别background_surface属性primary变体inverse状态hoverswitch_thumb-disabledswitch_thumb开关的滑钮的disabled状态core-white_constantcore类别下white_constant恒定的白色不受主题影响。理解了这套规则任何新出现的键都可以按结构反推其用途。五、v2 可用配色键分类速查下面把MetabaseEmbeddingColorKeyV2中保留可用的键按语义分组便于在实际定制时快速定位语义与状态保留danger、focus、gold、summarize、success-secondary、white、saturated-{blue,green,purple,red,yellow}剔除filter、info、warning、success、error、shadow、全部accent*背景 Background旧命名Legacybackground-{brand,filter,disabled,disabled-inverse,error,error-secondary,highlight,hover,info,primary,primary-inverse,secondary,secondary-inverse,selected,success,success-secondary,tertiary,tertiary-inverse,warning,warning-secondary}页面级background_page-{filter,highlighted,primary,primary-inverse,secondary,secondary-inverse,tertiary,tertiary-inverse}表面级background_surface-*含brand-strong、brand-subtle、error、error-subtle、hover、primary、primary-inverse、secondary、secondary-inverse、selected、success、warning、warning-strong及其hover/pressed状态边框 Border旧命名border、border-strong、border-stronger、border-subtle新命名border-{brand,filter,highlight,neutral,neutral-strong,neutral-strongest,neutral-subtle,on_dark}文本 Text 与图标 Icon文本text-{primary,primary-inverse,secondary,secondary-inverse,tertiary,tertiary-inverse,disabled,disabled-inverse,selected,hover,brand,brand-hover,brand-strong,brand-strong-hover,filter,syntax-parameter,syntax-parameter-active,secondary-opaque}图标icon-{brand,brand-inverse,disabled,disabled-inverse,primary,primary-inverse,secondary,secondary-inverse}品牌与派生色 Corecore-brand、core-brand-hover、core-filter、core-summarize、core-white、core-white_constant、core-gold、core-info、core-{blue,green,purple,red,yellow}-saturated注意core-metabase_brand与core-metabase_brand-hover是保护色不在可用范围内反馈、输入、开关、工具提示等组件级feedback-{negative,negative-strong,neutral-strong,positive,positive-selected,positive-strong,warning,warning-strong}input-{background,focus}、modal-overlay、shadow-defaultswitch-{checked,disabled,unchecked}、switch_thumb-disabledtooltip-{background,background-focused,text,text-secondary}syntax-parameters、syntax-parameters-active深色场景按钮button-on_dark-*与button-label-on_dark-*各含primary/secondary的default/hover/pressed与disabled状态插画类illustration-{secondary-brand,tertiary-brand,brand-secondary,brand-tertiary}、overlay六、实战在 MetabaseEmbeddingThemeV2 中使用配色键MetabaseEmbeddingColorKeyV2的消费方是 v2 主题配置MetabaseEmbeddingThemeV2定义见 MetabaseEmbeddingThemeV2.md。其属性表如下继承自原文档PropertyTypeDescriptionchartColors?ChartColorV2[]Chart colors overrides. Each color can be a string or an object with base/tint/shade.colors?PartialRecordMetabaseEmbeddingColorKeyV2, stringColor overrides.version2Theme version must be 2 for version 2 themes.可以看到colors字段的键类型正是本文主角MetabaseEmbeddingColorKeyV2——配合PartialRecord...意味着你只能使用上述白名单内的键且每个键都是可选覆写。一个最小可用的 v2 嵌入主题示例import { MetabaseProvider, type MetabaseEmbeddingThemeV2, } from metabase/embedding-sdk-react; const theme: MetabaseEmbeddingThemeV2 { version: 2, // 必须是 2否则不属于 v2 主题 colors: { // 以下均为 MetabaseEmbeddingColorKeyV2 白名单内的键 brand: #3A6EA5, brand-hover: #2F5A87, background_page-primary: #F7F8FA, background_surface-primary: #FFFFFF, background_surface-primary-hover: #F1F3F7, text-primary: #1F2937, text-secondary: #6B7280, border: #E5E7EB, border-neutral: #D1D5DB, focus: #3A6EA5, danger: #DC2626, success-secondary: #22C55E, }, chartColors: [ { base: #3A6EA5, tint: #6E93BF, shade: #2F5A87 }, // accent0 由这里派生 #F59E0B, // 也可以直接给字符串 { base: #10B981 }, // ...最多对应 accent0 ~ accent7 共 8 组 ], }; export function App() { return ( MetabaseProvider authConfig{authConfig} theme{theme} {/* 嵌入组件 */} /MetabaseProvider ); }chartColors的类型是ChartColorV2支持三种形态type ChartColorV2 | string // 简单颜色字符串 | { base: string; // 基础色 shade?: string; // 基础色的深色变体 tint?: string; // 基础色的浅色变体 } | null; // 显式置空这正是前文强调的“强调色走 chartColors、不走 colors 键”的落点colors里没有accent0图表系列的 8 组强调色只能通过chartColors数组传入再由主题引擎映射回accent0~accent7。七、源码实现主题键如何被解析与合并颜色键从“嵌入方传入”到“最终生效”的完整链路集中在 derive-theme.ts 的deriveFullMetabaseTheme函数中。源码注释明确了合并优先级Priority: base theme colors appearance settings whitelabel colors modular embedding theme overrides即基础主题 应用外观白标配置 模块化嵌入主题覆写后者的优先级更高。合并逻辑可拆解为四步过滤保护色_.omit(embeddingThemeOverride?.colors, ...PROTECTED_COLORS)剔除嵌入方传入的所有保护色键逐层展开基础主题baseTheme.colors→ 基础主题的chartColors映射为强调色mapChartColorsToAccents→ 白标配置派生的强调色deriveAllAccentColors→ 过滤后的嵌入colors→ 嵌入方chartColors映射的强调色按序展开合并派生品牌键合并完成后将brand、filter、summarize的实际值分别回填到core-brand、core-filter、core-summarize见源码 derive-theme.ts 的 GDGT-2517 兼容层注释保证新旧命名始终指向同一实际颜色输出完整主题返回{ version: 2, colors }形式的MetabaseDerivedThemeV2其中colors覆盖MetabaseColorKey全量键。这一步在源码中表现为mapChartColorsToAccents见 accents.ts 与 derive-theme.ts嵌入方在chartColors里写的每一组base/tint/shade最终都会成为图表中accentN、accentN-dark、accentN-light的实际取值。这也是MetabaseEmbeddingColorKeyV2刻意把accent*排除在外的根本原因——它们有专门的输入通道。八、相关类型与延伸阅读MetabaseEmbeddingColorKeyV2处于一套相互关联的类型体系中MetabaseColorKey.md全量颜色键父集MetabaseEmbeddingColorKeyV2由它经Exclude派生源码见 color-keys.tsProtectedColorKey.md保护色键集合运行时对应 protected-colors.ts 的PROTECTED_COLORSMetabaseEmbeddingThemeV2.mdv2 主题配置对象colors字段消费本类型ChartColorV2.md图表强调色定义string | { base, tint?, shade? } | nullMetabaseEmbeddingTheme.mdMetabaseTheme | MetabaseEmbeddingThemeV2的联合类型是MetabaseProvider的theme属性实际接受的类型完整 API 索引见 snippets/index.md主题定制的完整指南见 appearance.md。九、小结MetabaseEmbeddingColorKeyV2是 Metabase 模块化嵌入主题系统的一等公民它以ExcludeMetabaseColorKey, 剔除项 | ProtectedColorKey的方式定义了嵌入方可用的全部配色键把品牌色、管理端配色与图表强调色挡在门外同时保留了背景、边框、文本、图标、反馈、工具提示等约 150 个可定制键。定制 v2 主题时记住两条铁律即可version必须为 2强调色走chartColors其余颜色走colors且不能使用accent*键。类型约束与deriveFullMetabaseTheme的运行时过滤双重保障让嵌入体验在高度可定制与品牌一致性之间取得平衡。【免费下载链接】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），仅供参考