前端星盤 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);
});

以下是一個即時互動的樣式自定義演示，支援單盤與雙盤模式切換。你可以直接拖動滑塊、選擇顏色，立即看到視覺反饋。