组件样式管理逻辑

relation-graph 的样式系统由三层组成：

1. 数据字段：node.color、line.lineWidth 等，表达图谱元素的核心视觉语义。
2. 全局配置：RGOptions.defaultNodeColor、defaultLineColor 等，提供默认值。
3. CSS 变量与类名：最终控制 DOM 渲染细节、状态样式和主题扩展。

理解这三层关系非常重要。只改 CSS 可以改变主视图外观，但缩略图、EasyView、导出分析、自动分类等能力更依赖数据字段和有效样式。

1. 根节点与 CSS 变量

图谱根节点类名是：

.relation-graph

框架组件会把部分 RGOptions 写成根节点内联 CSS 变量：

CSS 变量	来源配置	默认值	影响
--rg-background-color	options.backgroundColor	transparent	.rg-map 背景色。
--rg-checked-item-bg-color	options.checkedItemBackgroundColor	CSS 默认 rgba(150,150,150,0.2)	checked 节点光圈、checked 线热区等。
--rg-node-color	options.defaultNodeColor	#ffffff	默认节点背景色。
--rg-node-border-color	options.defaultNodeBorderColor	#666666	默认节点边框色。
--rg-node-border-width	options.defaultNodeBorderWidth + 'px'	1px	默认节点边框宽度。
--rg-node-border-radius	options.defaultNodeBorderRadius + 'px'	4px	默认矩形节点圆角。
--rg-line-color	options.defaultLineColor	#cccccc	默认线条颜色。
--rg-line-width	options.defaultLineWidth + 'px'	2px	默认线条宽度。

SCSS 中还定义了一批基础变量：

CSS 变量	默认值	说明
--rg-node-opacity	1	节点整体透明度。
--rg-node-font-size	1rem	节点文字字号。
--rg-node-font-color	#000000	节点文字颜色。
--rg-node-width	fit-content	默认节点 DOM 宽度。
--rg-node-height	fit-content	默认节点 DOM 高度。
--rg-node-text-px	10px	默认节点文本左右内边距。
--rg-node-text-py	3px	默认节点文本上下内边距。
--rg-line-fontcolor	var(--rg-line-color, #666666)	连线文本颜色。
--rg-line-fontsize	12px	连线文本字号。
--rg-line-opacity	1	连线透明度。
--rg-checked-line-text-bg-color	rgb(234, 232, 232)	checked 连线文本背景。

你可以在图谱外层加命名空间后覆盖：

.my-graph .relation-graph {
  --rg-node-font-size: 13px;
  --rg-node-text-px: 12px;
  --rg-line-fontsize: 11px;
  --rg-checked-line-text-bg-color: #e0f2fe;
}

2. 数据字段到 CSS 变量的链路

节点最终渲染时会综合：

1. 节点自身字段：node.color、node.borderColor、node.borderWidth、node.borderRadius、node.opacity、node.fontColor、node.fontSize、node.width、node.height、node.zIndex。
2. 全局默认值：defaultNodeColor、defaultNodeBorderColor 等。
3. CSS 变量和 DOM 类。

连线最终渲染时会综合：

1. 连线自身字段：line.color、line.lineWidth、line.opacity、line.fontColor、line.fontSize、line.dashType、line.animation。
2. 全局默认值：defaultLineColor、defaultLineWidth、defaultLineTextOffsetX 等。
3. CSS 变量、SVG marker、路径类名。

推荐原则：

• 核心语义颜色、宽度、形状写进节点/连线数据。
• 全局基线写进 RGOptions。
• 主题微调和状态效果写 CSS。

不推荐：

/* 不推荐作为唯一来源 */
.my-node-card {
  background: red;
}

.relation-graph .rg-line {
  stroke: red;
}

如果只这样写，主视图可能变了，但缩略图、EasyView、样式分析和导出语义可能仍认为节点/线是默认颜色。

3. DOM 层级结构

简化层级如下：

.relation-graph
  .rg-map
    .rg-map-background
    .rg-map-canvas
      .rg-canvas-behind
        .rg-canvas-slot.rg-canvas-slot-behind
      .rg-lines-container
        svg.rg-lines-svg
          .rg-line-peel
            path.rg-line-bg
            path.rg-line
            text.rg-line-text
      .rg-linetext-container
        .rg-line-peel
          .rg-line-label
      .rg-nodes-container-wrapper
        .rg-nodes-container
          .rg-node-peel
            .rg-node
              .rg-node-text
      .rg-canvas-above
        .rg-canvas-slot.rg-canvas-slot-above
  .rg-graph-plugs
    .rg-view-slot

层级含义：

层	说明
.relation-graph	根容器，承载全局类名、CSS 变量、焦点和键盘事件。
.rg-map	视口层，负责背景、裁剪、用户拖拽/滚轮交互。
.rg-map-canvas	画布坐标层，平移和缩放 transform 作用于这一层。
.rg-canvas-behind	画布下层插槽，随画布移动缩放。
.rg-lines-container	SVG 连线路径层。
.rg-linetext-container	HTML 连线文本层。
.rg-nodes-container-wrapper	节点层。
.rg-canvas-above	画布上层插槽，随画布移动缩放。
.rg-graph-plugs .rg-view-slot	视图固定层，不随画布移动缩放。

4. 节点样式类

节点 DOM 结构：

<div class="rg-node-peel rg-node-shape-1 rg-node-type-service">
  <div class="rg-node">
    <div class="rg-node-text">API 服务</div>
  </div>
</div>

核心类：

类名	说明
.rg-node-peel	节点外层定位与状态承载层。transform、opacity、z-index 通常在这里。
.rg-node	节点视觉主体。背景、边框、宽高主要作用在这里。
.rg-node-text	默认节点文本。自定义节点插槽时可能不出现或结构不同。
.rg-node-shape-0	圆形节点。内部 .rg-node 会使用 border-radius: 50%。
.rg-node-shape-1	矩形节点。内部 .rg-node 会使用 --rg-node-border-radius。
.rg-node-type-{type}	按节点 type 生成的类型类名，适合分类主题。
node.className	你在节点数据中提供的自定义类名。

状态类：

类名	说明
.rg-node-checked	当前 checked 节点。默认提高 z-index，并给 .rg-node 加外圈阴影。
.rg-node-selected	selected 节点。默认显示编辑色外圈。
.rg-node-dragging	正在拖拽的节点。源码预留状态类，具体效果可自定义。
.rg-node-disable-events	禁用节点事件。
.rg-node-hover	hover 相关预留类。

推荐覆盖方式：

.my-graph .relation-graph .rg-node-peel.rg-node-type-service > .rg-node {
  font-weight: 600;
}

.my-graph .relation-graph .rg-node-peel.rg-node-checked > .rg-node {
  box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.2);
}

.my-graph .relation-graph .rg-node-peel.node-error > .rg-node {
  border-color: #dc2626;
}

同时建议数据中保留核心语义：

{
  id: 'api',
  text: 'API',
  type: 'service',
  className: 'node-error',
  color: '#fef2f2',
  borderColor: '#dc2626'
}

5. 连线样式类

连线路径 DOM 结构简化：

<g class="rg-line-peel rg-line-checked" data-id="line-a-b">
  <path class="rg-line-bg"></path>
  <path class="rg-line rg-line-dashtype-2 rg-line-anm-1"></path>
</g>

HTML 文本层：

<div class="rg-line-peel" data-id="line-a-b">
  <div class="rg-line-label">调用</div>
</div>

核心类：

类名	说明
.rg-line-peel	连线外层状态承载层。
.rg-line	真正可见的 SVG path。颜色、宽度、箭头 marker 作用在这里。
.rg-line-bg	更宽的透明点击热区。hover 和 checked 高亮常作用在这里。
.rg-line-text	SVG textPath 文本。
.rg-line-label	HTML 线文本标签。
.rg-line-disable-events	禁用连线事件。
.rg-line-checked	当前 checked 连线状态。
.rg-line-selected	selected 连线状态，源码预留。

虚线预设：

类名	来源	效果
.rg-line-dashtype-1	line.dashType = 1	stroke-dasharray: 2, 2, 2
.rg-line-dashtype-2	line.dashType = 2	stroke-dasharray: 5, 5, 5
.rg-line-dashtype-3	line.dashType = 3	stroke-dasharray: 9, 9, 9
.rg-line-dashtype-4	line.dashType = 4	stroke-dasharray: 5, 5, 15

动画预设：

类名	来源	说明
.rg-line-anm-1	line.animation = 1	线条虚线流动，10s 线性循环。
.rg-line-anm-2	line.animation = 2	虚线偏移动画，3s 循环。
.rg-line-anm-3	line.animation = 3	透明度闪烁动画，1s 循环。
.rg-line-anm-4	line.animation = 4	线条绘制感动画，3s 循环。

推荐覆盖方式：

.my-graph .relation-graph .rg-line-peel.line-warning .rg-line {
  filter: drop-shadow(0 0 3px rgba(245, 158, 11, 0.45));
}

.my-graph .relation-graph .rg-line-checked .rg-line-bg {
  stroke: rgba(37, 99, 235, 0.2);
}

.my-graph .relation-graph .rg-linetext-container .rg-line-label {
  border: 1px solid #e2e8f0;
  background: #ffffff;
}

对应数据：

{
  id: 'line-a-b',
  from: 'a',
  to: 'b',
  text: '告警链路',
  className: 'line-warning',
  color: '#f59e0b',
  lineWidth: 3,
  dashType: 2,
  animation: 1
}

6. 画布、背景和插槽层样式

类名	层级	说明
.rg-map-background	背景层	背景插槽/背景能力相关容器。
.rg-canvas-slot	画布插槽	所有 canvas 插槽的基础类。
.rg-canvas-slot-behind	canvas 下层	z-index 默认低于节点/线。
.rg-canvas-slot-above	canvas-above 上层	z-index 默认高于节点/线。
.rg-view-slot	view 层	视图固定层内容容器。

注意：

• canvas 和 canvas-above 在画布坐标系中，随画布 transform 移动/缩放。
• view 在视口层，不随画布 transform。
• 背景插槽位于底层，更适合水印、固定背景或导出背景。

7. 编辑器相关样式类

编辑能力会用到这些类：

类名	说明
.rg-editing-ctrl	节点编辑控制器外框。
.rg-editing-line-ctrl	连线编辑控制器。
.rg-editing-connect-ctrl	节点连接控制器外框。
.rg-editing-bar	节点附近工具条基础类。
.rg-editing-bar-top/right/bottom/left/tl/tr/bl/br	工具条位置类。
.rg-connect-source-handle	连线起点拖拽区域。
.rg-connect-target	可连接目标区域。
.rg-connect-ctl-*	连接控制器上的各方向控制点。
.rg-selection	框选区域。
.rg-miniview	缩略图。
.rg-toolbar	工具栏。

推荐：

.my-graph .relation-graph {
  --editor-main-color: #2563eb;
  --editor-light-color: #60a5fa;
  --editor-light2-color: #bfdbfe;
  --editor-light-opacity: rgba(37, 99, 235, 0.1);
}

编辑器类样式最好通过外层命名空间约束，避免影响站点其他图谱。

8. 根节点状态类

根节点 .relation-graph 会根据运行时状态添加类：

类名	来源	影响
.rg-creating-line	options.creatingLinePlot	表示正在创建连线，可用于改变光标或提示。
.rg-move-mode	options.dragEventAction === 'move'	.rg-map 光标变为 grab。
.rg-enable-node-xy-animation	options.enableNodeXYAnimation	.rg-node-peel 位置变化启用 150ms transition。
.rg-enable-canvas-animation	options.enableCanvasTransformAnimation	.rg-map-canvas transform 启用 0.5s transition；编辑控制器会短暂隐藏。

示例：

.my-graph .relation-graph.rg-creating-line {
  cursor: crosshair;
}

9. 样式优先级建议

推荐顺序：

1. RGOptions 设置默认主题。
2. node/line 数据字段设置业务差异。
3. className 或 type 做分类样式。
4. 外层命名空间 CSS 做项目主题。
5. 插槽内部 CSS 做复杂内容布局。

示例：

const graphOptions = {
  defaultNodeColor: '#ffffff',
  defaultNodeBorderColor: '#cbd5e1',
  defaultLineColor: '#94a3b8',
  defaultLineWidth: 2
};

const node = {
  id: 'risk-node',
  text: '高风险服务',
  type: 'service',
  className: 'node-risk',
  color: '#fef2f2',
  borderColor: '#ef4444'
};

.my-graph .relation-graph .rg-node-peel.node-risk > .rg-node {
  box-shadow: 0 6px 16px rgba(239, 68, 68, 0.12);
}

这样主视图、缩略图、导出语义和自定义视觉都能尽量保持一致。

10. 自定义节点插槽时的样式边界

使用 #node 后，默认节点外壳仍存在，但内部内容由你渲染。

建议：

• 仍然设置 node.color、node.borderColor、node.width、node.height。
• 插槽内部负责复杂结构，例如图标、指标、按钮、状态行。
• 如果插槽内容会超出默认节点宽高，显式设置 width/height，避免布局和连线交点延迟抖动。

不建议：

• 完全依赖内部卡片宽高，但不告诉节点数据实际尺寸。
• 在内部按钮上阻止事件后忘记处理节点选择/拖拽关系。

11. 自定义连线插槽时的样式边界

使用 #line 后，你可以完全自定义路径和文本。但仍建议：

• 使用 line.color、line.lineWidth 表达核心线条语义。
• 使用 graphInstance.generateLinePath(lineConfig) 获取路径信息。
• 转发点击/hover 等事件到统一逻辑，避免默认交互和自定义交互分裂。
• 对复杂动画使用 line.className 或 line.animation 做数据层标记。

12. 常见问题

为什么 CSS 改了主图，但缩略图没变？

缩略图主要使用节点/连线数据字段绘制，不会完整解析你写给 DOM 的所有 CSS。核心颜色、宽度、形状应写进数据字段或 RGOptions。

为什么节点 checked 样式覆盖不了？

默认 checked 样式作用在：

.rg-node-peel.rg-node-checked > .rg-node

你的选择器需要有足够优先级，并且最好加外层命名空间：

.my-graph .relation-graph .rg-node-peel.rg-node-checked > .rg-node {
  box-shadow: 0 0 0 4px rgba(16, 185, 129, 0.25);
}

为什么线文本有两套 DOM？

relation-graph 支持两种线文本：

• HTML 标签：.rg-line-label，适合普通水平文本和复杂样式。
• SVG textPath：.rg-line-text，适合沿路径排版。

由 line.useTextOnPath 或 options.defaultLineTextOnPath 决定。

为什么点击区域比线条粗？

.rg-line-bg 是透明命中热区，默认宽度为 lineWidth + 6px。这是为了让细线更容易点击。禁用线事件可用 line.disablePointEvent 或 options.disableLinePointEvent。

13. 下一步阅读

• 图谱全局配置项
• 节点数据模型
• 连线数据模型
• 插槽系统概览
• 自定义节点
• 自定义连线