前端星盘 SVG 渲染开发文档

单位规范

所有 data-* 布局参数和 CSS 长度值均基于 SVG viewBox 单位（720×720），等同于像素单位。无特殊说明时均为绝对数值。

行星命名规则（data-object-id）

统一使用小写英文名 + 连字符格式：

• 单盘：planet-sun、planet-moon 等
• 双盘：planet-sun-a、planet-sun-b 等（严格追加 -a/-b）

本SVG星盘渲染器采用现代、可主题化的架构设计，原生支持完美响应式，完全分离几何结构与视觉样式，便于前端深度定制。

1. SVG 整体结构概述

• 根元素：<svg class="astrology-chart" data-layout-version="1.3">
• 主容器：<g class="chart" data-layout-token="chart-root">
• 分层结构（推荐通过 data-layer 控制显隐/动画）：
  • background：圆环与中心十字
  • zodiac：黄道十二宫符号
  • house：宫位线与数字（非轴线）
  • axis：轴线（ASC/DC、MC/IC）
  • aspect：相位线
  • planet：行星符号、度数、星座、逆行R

2. CSS 主题化（纯CSS即可完成）

.astrology-chart {
  --chart-ring-stroke: #333;
  --chart-aspect-hard-color: #ff4444;
  --chart-aspect-soft-color: #44aa44;
  --chart-connector-opacity: 0.6;
}

可控制的CSS变量列表（精选）

3. JS 高级自定义与交互属性（只读）

后端在渲染 SVG 时，已经为行星和宫位注入了极为丰富的占星数据，非常适合前端通过 JS 实现高级交互（例如：鼠标悬浮某宫位，高亮显示该宫内的所有行星）。

行星与宫位高级属性

• 精确经度：data-longitude="203.63"（附带于所有行星节点，可用于精确定位与运算）
• 落宫标识：data-house="1" 或类名 .in-house-1（附带于行星节点，表示该星落在第 1 宫）
• 四轴虚点：自带类名 .is-axis-point（专属于 ASC, MC, IC, DC，方便进行特殊样式过滤）

四轴与重点选择器

• 四轴宫位组：.house.is-axis（包含第 1, 4, 7, 10 宫的线条与数字节点，用于提取并加粗四轴线）
• 单个行星：#planet-sun 或 [data-object-id="planet-sun"]
• 单个相位：[data-aspect-type="square"] 或 [data-aspect-group="hard"]

行星专属交互热区与文本拆解

• 隐形交互热区：每个行星节点内包含一个 <circle class="planet-hit-area" data-interactive="planet" r="18" opacity="0">。这是专门为前端鼠标 Hover、Tooltip 或 Click 事件预留的扩大热区。因为行星文本和连线通常较细，很难精准悬停，绑定在这个 hit-area 上可以获得极佳的交互体验。
• 标签内容分块控制：行星旁边的信息组（符号、度数、星座、逆行标志）在 <g class="planet-label"> 内部被精确打上了 data-label-part 标签：
  • [data-label-part="symbol"]：天体符号（如 Su, Mo）
  • [data-label-part="position"]：精确度分（如 24°28'）
  • [data-label-part="sign"]：所在星座符号（如 ♈）
  • [data-label-part="retrograde"]：逆行标识（R）
  应用场景：你可以通过极简的 CSS 规则（例如 .astrology-chart [data-label-part="position"] { display: none; }）动态隐藏盘面上的杂乱度数信息，或者通过 JS 精确提取需要的特定文本进行二次渲染。

双盘模式与单盘模式架构完全统一，支持相同主题化方式，额外提供内外盘独立颜色控制。目前仅绘制 A↔B 互动相位（inter）。

1. SVG 整体结构概述

• 分层结构（新增）：
  • planet-a：内盘（Person A），data-person="a"
  • planet-b：外盘（Person B），data-person="b"

2. CSS 主题化（双盘专属差异部分）

3. JS 高级自定义（双盘专属）

• 双盘专属相位范围 (Scope)：双盘的根节点 <g class="chart"> 包含了 data-aspect-scope="inter" 属性。这明确标识了当前渲染层级的数据物理含义，即目前绘制的相位线纯粹是 Person A 与 Person B 之间的交叉互动（inter）相位，而非单人的本命相位。
• 双盘专属相位连线属性：双盘的相位连线区分了内外盘，使用 data-planet-a="{code}" 和 data-planet-b="{code}" 属性（单盘为 data-planet1 和 data-planet2）。例如选中 A 盘太阳的相位：[data-planet-a="0"]。
• 内盘行星：[data-layer="planet-a"]
• 单个行星（区分内外）：#planet-sun-a（内盘太阳）、#planet-sun-b（外盘太阳）

以下是一个实时互动的样式自定义演示，支持单盘与双盘模式切换。你可以直接拖动滑块、选择颜色，立即看到视觉反馈。