G6 自定义主题（Custom Theme）完整指南：从配置结构到源码实现

G6 自定义主题Custom Theme完整指南从配置结构到源码实现【免费下载链接】G6♾ A Graph Visualization Framework in JavaScript.项目地址: https://gitcode.com/gh_mirrors/g6/G6G6antv/g6是一款 JavaScript 图可视化框架主题Theme是其样式体系的核心机制之一主题本质上是 Graph Options 的一个子集集中管理画布与节点node、边edge、组合combo元素的样式让你能够一键切换整套图风格。本文将基于packages/site/docs/manual/theme/custom-theme.en.md文档结合仓库源码深入讲解主题的配置结构、静态约束、注册与切换方法并剖析内置主题的 token 实现机制帮助你在实际项目中快速定制并动态切换主题。主题的本质Graph Options 的子集在 G6 中主题不是一套独立的样式引擎而是 Graph Options 的子集。它只包含与画布和元素样式相关的配置作用是在不改变图数据与布局的前提下快速切换整套视觉风格。从类型定义可以直观看到主题的边界。在 packages/g6/src/themes/types.ts 中主题被定义为export type Theme { node?: StaticNodeOptions; edge?: StaticEdgeOptions; combo?: StaticComboOptions; background?: string; };而 Graph 的theme选项类型在 packages/g6/src/spec/theme.ts 中为export type ThemeOptions false | light | dark | string;也就是说theme可以是false关闭主题、内置主题名light/dark或任意已注册的自定义主题名字符串。G6 在初始化时会读取该选项并应用对应的主题配置。主题包含的配置项主题配置共包含四个顶层字段配置项类型说明backgroundstring画布背景色nodeStaticNodeOptions节点样式及状态样式edgeStaticEdgeOptions边样式及状态样式comboStaticComboOptions组合combo样式及状态样式一个典型的主题配置示例如下const theme { background: #fff, node: { style: { fill: #e1f3fe, lineWidth: 0, }, selected: { style: { fill: #3b71d6, lineWidth: 1, }, }, }, edge: { // 边的默认样式与状态样式 }, combo: { // 组合的默认样式与状态样式 }, };其中node、edge、combo的style描述元素的默认样式而selected、active、highlight、inactive、disabled等字段则描述对应状态state下的样式覆盖。这与 G6 元素状态样式state style机制保持一致——主题中的状态样式同样由元素的状态系统在交互时应用。主题的静态约束不支持 type 与回调函数主题内的元素样式是静态配置存在两条硬性约束不支持配置元素类型type元素的类型如rect、circle、line等属于元素注册与选型层面应在 Graph 的node/edge/combo选项中指定而非主题。主题只负责给定类型下的样式表现。不支持回调函数动态计算样式主题中的属性值必须是确定的静态值颜色、数字、布尔值等不能像元素级配置那样使用(d) d.style.color之类的回调函数。以下为错误示例const theme { node: { // ❌ 主题不支持配置元素类型 type: rect, style: { // ❌ 主题不支持回调函数 fill: (d) d.style.color, }, }, };从类型定义上也能印证这一点packages/g6/src/themes/types.ts 中node、edge、combo使用的是StaticNodeOptions、StaticEdgeOptions、StaticComboOptions类型定义于 packages/g6/src/spec/element/ 下的 node.ts、edge.ts、combo.tsStatic前缀即表明其为静态配置不支持函数形式的动态求值。状态样式注意事项:::warning{title注意} 对于元素状态样式请确保状态样式中的每一个属性在默认样式style中都有对应的默认值否则可能导致状态样式无法被清除。 :::例如若在selected状态样式中配置了lineWidth则默认style中也需要有lineWidth字段否则当元素退出selected状态时G6 无法找到可还原的默认值状态样式将残留。这一约束是保证状态切换可逆、可清除的前提。注册自定义主题自定义主题需要通过 G6 提供的register方法注册到扩展注册表中方可被 Graph 使用import { register, ExtensionCategory } from antv/g6; register(ExtensionCategory.THEME, custom-theme, theme);ExtensionCategory.THEME指定扩展类别为主题custom-theme是主题的注册名即后续theme选项引用的标识theme是前文定义的主题配置对象。从源码看主题与元素、插件、布局等一样被存放在统一的扩展注册表中注册表类型定义于 packages/g6/src/registry/types.tstheme: Recordstring, Theme存储容器在 packages/g6/src/registry/store.ts注册与获取逻辑位于 packages/g6/src/registry/register.ts 与 packages/g6/src/registry/get.ts。G6 内置的light与dark主题同样通过这一机制注册见 packages/g6/src/registry/build-in.ts其中theme字段将dark、light两个内置主题映射进注册表。在 Graph 中配置主题注册完成后在实例化Graph时传入theme选项即可启用const graph new Graph({ container: container, data: {...}, theme: custom-theme, });在运行时层面theme选项会在初始化与setOptions时被解析并应用。查看 packages/g6/src/runtime/graph.ts_setOptions在处理选项时会执行if (theme) this.setTheme(theme)初始化时的默认主题在 packages/g6/src/runtime/graph.ts 中被设置为light。也就是说即使不显式配置themeG6 也会默认套用浅色主题。切换主题setTheme / getThemeGraph 实例创建后可以随时通过setTheme方法动态切换主题graph.setTheme(dark);也可以传入一个函数基于当前主题返回新主题函数式更新graph.setTheme((prev) (prev dark ? light : dark));使用getTheme获取当前主题graph.getTheme(); // dark这两个方法的实现位于 packages/g6/src/runtime/graph.tsgetTheme直接返回this.options.themesetTheme在入参为函数时先以当前主题调用函数求出新值再写回this.options.theme从而驱动元素与画布按新主题重绘。public getTheme(): ThemeOptions { return this.options.theme!; } public setTheme(theme: ThemeOptions | ((prev: ThemeOptions) ThemeOptions)): void { this.options.theme isFunction(theme) ? theme(this.getTheme()) : theme; // ...触发重绘逻辑 }实际使用中setTheme非常适合用于明暗模式切换、报表主题联动等场景只需维护多个注册好的主题运行时一行代码即可完成整套样式的切换无需重新创建 Graph 或重新渲染数据。源码纵深内置主题的 token 机制为了更高效地维护内置主题G6 并没有直接手写Theme对象而是通过一套 token设计变量机制生成。以 packages/g6/src/themes/light.ts 为例它先定义一组语义化 tokenconst tokens { bgColor: #ffffff, comboColor: #99ADD1, edgeColor: #99add1, nodeColor: #1783ff, nodeStroke: #000000, textColor: #000000, // ... }; export const light: Theme create(tokens);dark主题packages/g6/src/themes/dark.ts则复用相同结构、替换 token 取值例如bgColor: #000000、textColor: #ffffff并额外配置了边颜色的分组调色板EDGE_PALETTE_OPTIONS。create函数packages/g6/src/themes/base.ts负责将 token 展开为完整的主题对象包括node默认style如fill、size、labelFill、zIndex、状态stateselected/active/highlight/inactive/disabled各自的 halo、透明度、线宽等、以及animation进入/退出/更新的动画配置如fade、node-expandedge默认样式、五类状态样式、动画配置如path-in/path-outcombo默认样式含collapsedSize、collapsedMarkerFill等折叠态相关属性、状态样式、动画配置如combo-expand/combo-collapse。这解释了为什么内置主题的状态切换选中、悬停、高亮、禁用有完整的动画与透明度过渡效果——它们都来自create展开的完整结构。如果你需要自定义主题除了直接编写Theme字面量也可以参考这套 token 思路定义一组语义化颜色变量再据此生成多个明暗变体主题复用性与可维护性更高。实战完整的自定义主题示例综合以上内容一个完整可运行的自定义主题流程如下import { Graph, register, ExtensionCategory } from antv/g6; // 1. 定义主题配置静态样式不支持 type 与回调函数 const brandTheme { background: #f7f9fc, node: { style: { fill: #e1f3fe, lineWidth: 0, size: 36, }, selected: { style: { fill: #3b71d6, lineWidth: 1, }, }, }, edge: { style: { stroke: #99add1, lineWidth: 1, }, active: { style: { lineWidth: 3, }, }, }, combo: { style: { fill: #eef3fb, stroke: #99add1, }, }, }; // 2. 注册主题 register(ExtensionCategory.THEME, brand-theme, brandTheme); // 3. 实例化 Graph 时启用 const graph new Graph({ container: container, data: { nodes: [{ id: node-1, style: { x: 100, y: 100 } }], edges: [], }, theme: brand-theme, }); // 4. 运行时切换为内置深色主题 graph.setTheme(dark); console.log(graph.getTheme()); // dark总结G6 的主题机制可以概括为三点主题 Graph Options 的子集只管理background、node、edge、combo四类静态样式配置主题配置是静态的不支持type与回调函数且状态样式的每个属性都应在默认样式中存在对应值主题可注册、可配置、可动态切换通过register(ExtensionCategory.THEME, ...)注册在 Graph 选项中启用并用setTheme/getTheme在运行时管理。理解了内置主题的 token 生成机制后你既可以编写最简主题字面量快速上色也可以借鉴create的思路构建可复用的主题体系。相关源码与文档入口custom-theme.en.md、主题类型定义、内置主题生成器、light 主题、dark 主题、setTheme/getTheme 实现。【免费下载链接】G6♾ A Graph Visualization Framework in JavaScript.项目地址: https://gitcode.com/gh_mirrors/g6/G6创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考