# Three 3d Component > Mini Taiwan Pulse 新增 Three.js × Mapbox 立體圖層的設計與接線手冊。當用戶說「新增 3D 圖層」「立體元件」「3D layer」「Three.js scene」「立體呈現」「3D 視覺化」「點與點的連結」「燈塔轉圈/光柱/巨蛋/光弧」或要從 `public/three-showcase.html`（68 元件案例庫）挑元件接到實際圖層時觸發。導引用戶從「想表達什麼語意」→ 對應元件類別 → Scene/CustomLayer 範本 → 必過 checklist（座標 / blending / dispose / 動態時間源 / 性能）→ 最後跑 tsc -b。 - Skill: `ianlkl11234s/three-3d-component` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ianlkl11234s/three-3d-component` - Raw SKILL.md: https://api.skillmd.com/api/skills/ianlkl11234s/three-3d-component/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: ianlkl11234s (https://skillmd.com/u/ianlkl11234s) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ianlkl11234s/three-3d-component --- # Three.js 3D 圖層設計手冊 > 目標：讓 Mini Taiwan Pulse 跳脫「只有點」的圖層形式。用立體幾何 + 動畫 + 光效 表達 **點的內涵**（燈塔轉圈）和 **點與點的關聯**（流動光弧、Sankey、力導向網路）。 > > SSOT： > - 案例庫：`public/three-showcase.html`（互動 demo，68 元件 9 大類） > - 元件查表：`docs/three-showcase-library.md` > - 已上線 Scene：`src/three/*Scene.ts`（16 個） > - CustomLayer 接線：`src/map/*CustomLayer.ts` --- ## 一、何時用 3D，何時不用 | 情境 | 用 3D？ | 改用 | |---|---|---| | 單點靜態 POI（≤ 200 個，無時序） | ❌ | Mapbox `circle` / `symbol` | | 大量點分佈（>1000）需呈現密度 | ❌ | h3 hexbin / heatmap | | 點本身有語意動作（轉、發光、脈動） | ✅ | beam / radar / orb | | 點與點之間有關係（流動、層級） | ✅ | flowline / arc / sankey / network | | 範圍 / 影響力 / 覆蓋 | ✅ | dome / cone / ripple / hexgrid | | 時序動態（隨 timeline 變化） | ✅ | 走 Three.js + timeStore | **鐵則**：3D 是為了「**表達語意**」，不是為了酷。下手前先回答這題： > 「拿掉這個 3D 元件，使用者會少看懂什麼？」 答不出來 → 用 2D。 --- ## 二、設計流程（5 步） ### Step 1：定義語意 填寫這個句子： > 「這個圖層的每個物件，是一個 **［主體名詞］**，它正在 **［動作 / 狀態 / 關係］**，影響範圍 **［大小 / 方向 / 對象］**。」 範例： - 燈塔 = 一座 **燈塔**，正在 **旋轉發光**，影響 **半徑 N 公里的海域** → `beam` + 旋轉 - 火警分隊 = 一個 **救援基地**，正在 **發出脈動信號**，等時圈 **5/10/15 分鐘** → `cylinder` 光柱 + 多層 `ripple` - 列車調度 = 多個 **車站**，彼此之間 **班次流動**，方向 **北→南為主** → `flowline` / `arc` ### Step 2：對照元件類別 | 想表達 | 看類別 | 推薦元件 ID | |---|---|---| | 即時單一物件 | 基礎幾何 / 光效 | `orb` `beam` `pin` `crystal` | | 警示 / 脈動事件 | 動畫事件 | `ripple` `radar` `ring` `shockwave` `lightning` | | 範圍 / 勢力 / 保護罩 | 基礎幾何 | `dome` `cone` `lightcone` | | 數據量化（柱狀 / 等級） | 數據視覺化 | `bars` `polyextrude` `pie` `linechart` | | 流動 / 路徑 / 班次 | 線條 / 路徑 | `flowline` `arc` `network` | | 自然 / 氣體 / 大氣 | 體積 / 大氣 | `smoke` `noisecloud` `fog` | | 慶典 / 強調 / 特殊 POI | Shader 變形 / 場景 | `aurora` `flow` `firework` `text` | | 系統關係（多節點關聯） | 系統關係 | `sankey` `converge` `hydrocycle` `feedback` `cascade` | 完整對照查 `docs/three-showcase-library.md` 的「適合表達」欄位。 ### Step 3：在 showcase 試參數 在 dev 啟動 `npm run dev` → 開 `http://localhost:3721/three-showcase.html` → 找到對應元件 → 即時調 size / opacity / speed / color → **抄下用戶看得順的參數值**。 跳過這步是 80% 「上線後覺得太亮 / 太大」的根因。 ### Step 4：依骨架接線（看 §三） 新檔 + 強制順序，**禁** improvising。 ### Step 5：必過 checklist（看 §四） --- ## 三、Scene + CustomLayer 標準骨架 > 完整範例：複製 `src/three/LighthouseScene.ts` + `src/map/lighthouseCustomLayer.ts` 改名即可。 ### 3.1 必守接線 5 點 1. **共用 GL context**：`new THREE.WebGLRenderer({ canvas: gl.canvas, context: gl, antialias: true })` + `renderer.autoClear = false` 2. **座標轉換**：一律用 `src/utils/coordinates.ts` 的 `toMercator(lat, lng, alt)` — 不要自己算 mercator scale 3. **Blending 還原**：render() 前後備份 / 還原 `BLEND` 狀態（不然 Mapbox 之後的圖層會壞色）— 看 `LighthouseScene.render()` L66-96 是 SSOT pattern 4. **重繪驅動**：動態元件最後 `map?.triggerRepaint()`；靜態元件不要呼叫 5. **dispose**：`onRemove` 必走 `geometry.dispose()` + `material.dispose()` + `renderer.dispose()` ### 3.2 動態時間（時序圖層必看） ⚠️ **禁** 把 `currentTime` 放進 React `useEffect` / `useMemo` deps。 | 用法 | API | |---|---| | RAF / per-frame | `timeStore.getTime()` 同步讀 | | filter / lookup | `timeStore.subscribeThrottled(ms, cb)` | | 跨日載入 | `timeStore.subscribeDate(cb)` | | UI 顯示 | `useSyncExternalStore + subscribeThrottled(250)` | 理由見 `.claude/memory/feedback_dynamic_layer_principle.md`。 ### 3.3 Scene class 範本（最小） ```ts // src/three/MyScene.ts import * as THREE from "three"; import { toMercator } from "../utils/coordinates"; export class MyScene { private renderer!: THREE.WebGLRenderer; private scene = new THREE.Scene(); private camera = new THREE.Camera(); private groups: THREE.Group[] = []; private lastT = Date.now(); playing = true; init(gl: WebGLRenderingContext) { this.renderer = new THREE.WebGLRenderer({ canvas: gl.canvas as HTMLCanvasElement, context: gl as unknown as WebGL2RenderingContext, antialias: true, }); this.renderer.autoClear = false; } setPositions(positions: [number, number][]) { this.disposeGroups(); for (const [lng, lat] of positions) { const group = new THREE.Group(); const mc = toMercator(lat, lng, 0); group.position.set(mc.x, mc.y, mc.z); // → 在這裡建你的 mesh / shader / sprite this.scene.add(group); this.groups.push(group); } } render(matrix: number[]) { const gl = this.renderer.getContext(); const be = gl.isEnabled(gl.BLEND); const bs = gl.getParameter(gl.BLEND_SRC_RGB); const bd = gl.getParameter(gl.BLEND_DST_RGB); const bsa = gl.getParameter(gl.BLEND_SRC_ALPHA); const bda = gl.getParameter(gl.BLEND_DST_ALPHA); this.camera.projectionMatrix = new THREE.Matrix4().fromArray(matrix); const now = Date.now(); const dt = this.playing ? (now - this.lastT) / 1000 : 0; this.lastT = now; // → 在這裡更新動畫狀態（rotation / opacity sin / particle 位置） this.renderer.resetState(); this.renderer.render(this.scene, this.camera); this.renderer.resetState(); if (be) gl.enable(gl.BLEND); else gl.disable(gl.BLEND); gl.blendFuncSeparate(bs, bd, bsa, bda); } private disposeGroups() { for (const g of this.groups) { this.scene.remove(g); g.traverse((o) => { if (o instanceof THREE.Mesh) { o.geometry.dispose(); (o.material as THREE.Material).dispose(); } }); } this.groups = []; } dispose() { this.disposeGroups(); this.renderer?.dispose(); } } ``` CustomLayer 範本看 `src/map/lighthouseCustomLayer.ts`（53 行 SSOT）。 --- ## 四、必過 Checklist（新增 3D 圖層） ### A. 設計層 - [ ] 已填「§二 Step 1 語意句」並貼進 PR description - [ ] 元件 ID 從 `docs/three-showcase-library.md` 挑選（不自創） - [ ] 在 `three-showcase.html` 試過參數，截圖貼 PR ### B. 程式層（看「§5 新增 Layer 強制順序」CLAUDE.md） - [ ] `src/three/XxxScene.ts` 走 §3.3 骨架，blending 備份還原 - [ ] `src/map/xxxCustomLayer.ts` 走 §3.1 5 點 - [ ] 座標**一律** `toMercator(lat, lng, alt)`，禁手算 - [ ] `onRemove` 走完整 dispose ### C. 圖層 UX 四鐵則（CLAUDE.md §5a） - [ ] 透明度 slider（`useTransportParams.ts`） - [ ] 分類 ≥ 2 → `LegendPanel.tsx` + `LEGEND_REGISTRY` - [ ] 可點選 → `useMapInteraction.ts` + `featureInfo/registry.tsx` - [ ] Options ≥ 4 → 原生 `