前端星盘 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（外盘太阳）

默认情况下，星盘的星座图标（包括最外圈的黄道大环，以及内盘所有行星旁边的小星座符号）都是作为 Unicode 文本 渲染的。得益于统一的底层架构，以下替换逻辑 对单盘和双盘同时完美生效。只需通过简单的 JS 遍历，即可全局替换为你自己的精美 SVG 图形或外部图片。

完整替换逻辑代码参考：

// 1. 同时抓取外层大环 和 行星旁的小符号
const mainSigns = Array.from(document.querySelectorAll('[data-type="zodiac-sign"]'));
const planetSigns = Array.from(document.querySelectorAll('[data-label-part="sign"]'));
const allSigns = [...mainSigns, ...planetSigns];

// 2. 建立纯符号到英文的映射（用于识别行星旁的小符号名称）
const symbolToName = {
    '♈': 'aries', '♉': 'taurus', '♊': 'gemini', '♋': 'cancer',
    '♌': 'leo', '♍': 'virgo', '♎': 'libra', '♏': 'scorpio',
    '♐': 'sagittarius', '♑': 'capricorn', '♒': 'aquarius', '♓': 'pisces'
};

allSigns.forEach(node => {
    const x = Number(node.getAttribute('x'));
    const y = Number(node.getAttribute('y'));

    let signName = node.getAttribute('data-sign-name');
    let isPlanetIcon = false;

    // 如果没有 data-sign-name，说明它是行星旁的小符号
    if (!signName) {
        isPlanetIcon = true;
        signName = symbolToName[node.textContent.trim()];
    }

    // 3. 处理对齐偏移与缩放
    let offsetX = 0;
    let scale = 1;
    if (isPlanetIcon) {
        scale = 0.6; // 行星旁的小图标需要缩小至 60%
        const anchor = node.getAttribute('text-anchor');
        if (anchor === 'start') offsetX = 10;
        if (anchor === 'end') offsetX = -10;
    }

    // 4. 创建新容器并应用坐标与缩放
    const g = document.createElementNS("http://www.w3.org/2000/svg", "g");
    g.setAttribute("transform", `translate(${x + offsetX}, ${y}) scale(${scale})`);

    // 5. 插入自定义图片或路径
    // 方案 A：使用外部图片资源 (推荐)
    // const img = document.createElementNS("http://www.w3.org/2000/svg", "image");
    // img.setAttribute("href", `/assets/icons/${signName}.png`); // 动态读取对应星座图片
    // img.setAttribute("x", "-12"); img.setAttribute("y", "-12"); // 减去宽高一半居中
    // img.setAttribute("width", "24"); img.setAttribute("height", "24");
    // g.appendChild(img);

    // 方案 B：使用自定义 SVG Path (以简单的图形为例)
    const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
    path.setAttribute("d", "M 0 -12 L 3.52 -3.42 L 11.41 -2.76 L 5.41 2.34 L 7.23 10.02 L 0 5.68 L -7.23 10.02 L -5.41 2.34 L -11.41 -2.76 L -3.52 -3.42 Z");
    path.setAttribute("fill", "#ff0000");
    g.appendChild(path);

    // 6. 替换原生节点
    node.parentNode.replaceChild(g, node);
});

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