@xingwangzhe/tags-cloud：纯数学驱动的多模态 3D 标签云引擎

GitHub：xingwangzhe/tags-cloud · Demo：tagscloud.needhelp.icu · npm：@xingwangzhe/tags-cloud · License：MIT · Version：v0.9.0

1. 引言：为现代 Web 重新构想 3D 标签云

标签云作为 Web 可视化的常见元素已有超过二十年的历史，从简单的加权词列表演变为沉浸式的三维体验，吸引用户并将平淡的文字集合转化为可交互的空间雕塑。在这一演进过程中，cong-min/TagCloud 是最有影响力的贡献之一，这个轻量级 JavaScript 库展示了如何以极小的开销和零外部依赖实现一个旋转文本标签的球体。在 GitHub 上拥有 390 颗星 和 93 个 fork，原始 TagCloud 确立了一种设计模式，无数开发者将其用于个人作品集网站、技能展示和数据可视化仪表盘。其核心创新在于证明：3D 标签云无需依赖重量级 WebGL 框架或外部渲染引擎；相反，简单的三角函数计算配合精心的 DOM 定位就能产生令人惊艳的视觉效果。

@xingwangzhe/tags-cloud 登场 —— 这是对 3D 标签云概念的从头重新构想，保留了前作的数学优雅性，同时大幅扩展了其能力，现代化了其架构，并突破了标签云可渲染内容的边界。这不仅仅是一个 fork 或功能增强；它代表了从纯文本、DOM 密集型渲染器到 多模态引擎 的根本性架构转变，能够同时显示文本、图像、SVG 图形、任意 HTML、视频元素乃至完整的 Web Components —— 所有这些都在一个数学精确的三维空间中一起旋转。该库在实现这一多功能性的同时，保持了约 3KB gzipped 的超小体积，零运行时依赖，并使用完全现代化的工具链构建，包括 Bun 作为 JavaScript 运行时、Vite 作为打包器、TypeScript 提供整个代码库的完整类型安全。

项目的标语 —— “多模态 3D 标签云 · 纯数学引擎” —— 概括了其双重身份。一方面，它是一个实用的 UI 组件库，开发者可将其放入任何 Web 项目来创建视觉引人注目的标签球体。另一方面，它是一个数学引擎，将 3D 标签云渲染的复杂问题分解为三个纯粹、确定、且优美可分的几何操作：斐波那契球面分布 用于初始定位，旋转矩阵乘法 用于空间变换，透视投影 用于深度感知的 2D 渲染。这些操作各自实现在 src/core/ 目录下的独立模块中，使代码库不仅高度可维护，而且成为任何希望理解 3D 计算机图形学背后数学原理的人的极佳学习资源，且无需面对完整渲染管线的复杂迷雾。

以下章节将对 @xingwangzhe/tags-cloud 的各个方面进行全面的技术深入解析，从黄金比例衍生的球面分布算法到四元数启发的弧球交互模型，从双 Canvas/DOM 渲染架构到使其在桌面和移动设备上无缝运行的响应式设计考量。无论你是为下一个项目评估该库的开发者、对轻量级 3D 技术感兴趣的图形程序员，还是对斐波那契格点的实际应用感到好奇的数学家，本文都将提供详细的解释、数学推导、架构图和带注释的代码示例，以阐明这一杰出软件工程的每一个方面。

2. 数学基础：3D 渲染的三大支柱

@xingwangzhe/tags-cloud 的核心是三组数学运算，它们组合起来将抽象的内容列表转化为视觉连贯的旋转球体。这些运算 —— 分布、旋转和投影 —— 实现在 src/core/ 下的三个专用模块中，每个负责单一的几何变换。这种关注点分离不仅是架构上的偏好；它反映了 3D 计算机图形学管线的基本结构，其中顶点生成、模型变换和相机投影是不同阶段，可以独立优化、测试和理解。

flowchart LR
    subgraph Input["📥 输入层"]
        TAGS["TagItem[]
(text | image | SVG | HTML | video | element)"]
        OPTS["TagCloudOptions
(radius, spin, colors, callbacks)"]
    end

    subgraph CoreEngine["⚙️ 纯数学引擎 (src/core/)"]
        direction TB
        DIST["🔵 distribution.ts
斐波那契球面
N 个点 → 3D 坐标"]
        ROT["🟢 rotation.ts
旋转矩阵
3D 点 → 旋转后 3D 点"]
        PROJ["🔴 projection.ts
透视投影
旋转后 3D → 2D + 深度"]
    end

    subgraph RenderLayer["🎨 渲染层"]
        direction TB
        CANVAS["Canvas 2D API
(文本 + 图像)"]
        DOM["DOM 叠加层
(SVG + HTML + 视频 + 元素)"]
    end

    subgraph Interaction["👤 交互层"]
        MOUSE["鼠标 / 触摸拖拽"]
        INERTIA["惯性衰减
(0.96/帧)"]
    end

    TAGS --> DIST
    OPTS --> DIST
    DIST -->|"Vec3[]"| ROT
    ROT -->|"Rotated Vec3[]"| PROJ
    PROJ -->|"ProjectedTag[]
(x, y, z, scale, alpha)"| CANVAS
    PROJ --> DOM
    MOUSE --> INERTIA
    INERTIA -->|"旋转角度"| ROT

    style CoreEngine fill:#1a1a2e,stroke:#16213e
    style Input fill:#0f3460,stroke:#16213e
    style RenderLayer fill:#533483,stroke:#16213e
    style Interaction fill:#e94560,stroke:#16213e,color:#fff

2.1 斐波那契球面分布：点放置的黄金几何

创建 3D 标签云的第一步，也是视觉上最关键的一步，是确定每个标签在球面上的位置。一种天真的方法是在等间距的纬度和经度上放置标签，但这不可避免地会导致极点附近聚集（经线在此交汇）而赤道附近稀疏。斐波那契球面算法 优雅地解决了这个问题，它在整个球面上产生非常均匀的点分布，无论点的数量多少，都不会有明显的聚集或空隙。

该算法以 黄金比例 (\varphi = \frac{1 + \sqrt{5}}{2} \approx 1.6180339887) 命名，这个数学常数广泛出现在自然界中，从向日葵种子排列到鹦鹉螺壳螺旋。它与斐波那契数列（每个项是前两项之和）的联系在于，随着数列推进，连续斐波那契数的比值收敛于黄金比例。在球面分布的背景下，黄金比例的无理性确保连续的点始终以永不重复的角度放置，形成一种非周期性的螺旋图案，均匀覆盖球面。

src/core/distribution.ts 中的具体实现使用了一种针对球面映射优化过的斐波那契格点变体。对于一个半径为 (R)、需分布 (N) 个点的球体，算法计算球面坐标，然后将其转换为每个点 (i \in {0, 1, 2, \ldots, N-1}) 的笛卡尔坐标 ((x, y, z))。纬度角 (\phi)（从正 z 轴即北极测量）使用反余弦函数计算，以确保沿 z 轴的均匀分布：

$$\phi_i = \arccos\left(-1 + \frac{‘{’}2i + 1{‘}’}{‘{’}N{‘}’}\right)$$

这个公式将第一个点放在北极略下方，最后一个点放在南极略上方，(+0.5) 偏移量（嵌入在 (2i + 1) 分子中）确保没有任何点恰好落在极点上。这一微妙的调整至关重要，因为它防止了标签恰好位于球体顶部或底部的视觉瑕疵，在那里旋转几乎不可察觉。(\arccos) 函数将均匀分布的线性参数转换为余弦加权的角度分布，这补偿了球体在极点附近表面积较小、赤道附近较大的事实。

经度角 (\theta)（在 xy 平面中从正 x 轴测量）通过 (\phi) 乘以 (\sqrt{N\pi}) 来计算，这产生了特征性的螺旋图案：

$$\theta_i = \sqrt{‘{’}N\pi{‘}’} \cdot \phi_i$$

因子 (\sqrt{N\pi}) 源自黄金角度与球体总表面积之间的关系。随着 (N) 增大，这个缩放因子确保螺旋以适当的圈数缠绕球体，以维持相邻点之间的均匀间距。结果是一种模式，其中每个连续点相对于前一个点沿 z 轴方向旋转约 黄金角度 (\approx 137.5°)，与自然界中发现的叶序螺旋相呼应。

最后，这些球面坐标使用标准变换转换为笛卡尔坐标：

$$x_i = R \cdot \cos(\theta_i) \cdot \sin(\phi_i)$$

$$y_i = R \cdot \sin(\theta_i) \cdot \sin(\phi_i)$$

$$z_i = R \cdot \cos(\phi_i)$$

得到的点满足球面方程 (x_i^2 + y_i^2 + z_i^2 = R^2)，且均匀性堪比计算量更大、基于优化的方法。以下展示总结了完整的斐波那契球面算法：

$$\boxed{‘{’}\text{‘{’}FibonacciSphere{‘}’}(N, R): \quad \forall i \in [0, N-1]: \begin{‘{’}cases{‘}’} \phi_i = \arccos\left(-1 + \frac{‘{’}2i+1{‘}’}{‘{’}N{‘}’}\right) \ \theta_i = \sqrt{‘{’}N\pi{‘}’} \cdot \phi_i \ P_i = (R\sin\phi_i\cos\theta_i, ; R\sin\phi_i\sin\theta_i, ; R\cos\phi_i) \end{‘{’}cases{‘}’}{‘}’}$$

src/core/distribution.ts 中的 TypeScript 实现非常简洁，反映了该算法的优雅简单性：

export interface Vec3 { x: number; y: number; z: number; }

export function fibonacciSphere(n: number, R: number): Vec3[] {
  const points: Vec3[] = [];
  for (let i = 0; i < n; i++) {
    const phi = Math.acos(-1 + (2 * i + 1) / n);
    const theta = Math.sqrt(n * Math.PI) * phi;
    points.push({
      x: R * Math.cos(theta) * Math.sin(phi),
      y: R * Math.sin(theta) * Math.sin(phi),
      z: R * Math.cos(phi),
    });
  }
  return points;
}

该函数返回一个 Vec3 对象数组，作为云中所有标签的初始位置。算法运行时间为 (\mathcal{O}(N))，适用于包含数百个元素的标签云。实践中，大多数标签云包含 20 到 100 个标签，此计算几乎是瞬时完成的。

2.2 3D 旋转：空间域中的矩阵乘法

一旦标签定位在球面上，下一步是启用旋转 —— 既包括连续的自动旋转，也包括用户驱动的拖拽交互。该库使用 复合轴对齐旋转矩阵 来实现旋转，具体为先绕 Y 轴旋转，再绕 X 轴旋转。这种方法计算高效、易于理解，并且完全满足标签云用例的需求，其中旋转总是相对于以原点为中心的球体。

这些旋转的数学基础来自 线性代数。3D 旋转矩阵是一个 (3 \times 3) 的正交矩阵，行列式为 1，它在保持点到原点距离的同时变换点的坐标。对于绕 Y 轴旋转角度 (\alpha)，旋转矩阵 (R_y(\alpha)) 为：

$$R_y(\alpha) = \begin{‘{’}pmatrix{‘}’} \cos\alpha & 0 & \sin\alpha \ 0 & 1 & 0 \ -\sin\alpha & 0 & \cos\alpha \end{‘{’}pmatrix{‘}’}$$

对于绕 X 轴旋转角度 (\beta)，旋转矩阵 (R_x(\beta)) 为：

$$R_x(\beta) = \begin{‘{’}pmatrix{‘}’} 1 & 0 & 0 \ 0 & \cos\beta & -\sin\beta \ 0 & \sin\beta & \cos\beta \end{‘{’}pmatrix{‘}’}$$

该库顺序应用这些旋转：先绕 Y 轴，再绕 X 轴。对于点 (P = (x, y, z))，Y 轴旋转产生中间点 (P’)：

$$\begin{‘{’}pmatrix{‘}’} x' \ y' \ z' \end{‘{’}pmatrix{‘}’} = R_y(\alpha) \begin{‘{’}pmatrix{‘}’} x \ y \ z \end{‘{’}pmatrix{‘}’} = \begin{‘{’}pmatrix{‘}’} x\cos\alpha + z\sin\alpha \ y \ -x\sin\alpha + z\cos\alpha \end{‘{’}pmatrix{‘}’}$$

然后对 (P’) 应用 X 轴旋转，得到最终的旋转点 (P’’)：

$$\begin{‘{’}pmatrix{‘}’} x'' \ y'' \ z'' \end{‘{’}pmatrix{‘}’} = R_x(\beta) \begin{‘{’}pmatrix{‘}’} x' \ y' \ z' \end{‘{’}pmatrix{‘}’} = \begin{‘{’}pmatrix{‘}’} x' \ y'\cos\beta - z'\sin\beta \ y'\sin\beta + z'\cos\beta \end{‘{’}pmatrix{‘}’}$$

src/core/rotation.ts 中的实现将这些矩阵乘法展开为直接的算术运算，避免了矩阵对象分配和乘法的开销。对于单个点，旋转函数计算：

$$\boxed{‘{’}\begin{‘{’}aligned{‘}’} y_1 &= y \cdot \cos\alpha + z \cdot (-\sin\alpha) \ z_1 &= y \cdot \sin\alpha + z \cdot \cos\alpha \ x_2 &= x \cdot \cos\beta + z_1 \cdot \sin\beta \ z_2 &= z_1 \cdot \cos\beta - x \cdot \sin\beta \ P'' &= (x_2, ; y_1, ; z_2) \end{‘{’}aligned{‘}’}{‘}’}$$

rotatePoints 函数对所有标签批量执行此变换：

export function rotatePoints(points: Vec3[], a: number, b: number): Vec3[] {
  const sinA = Math.sin(a), cosA = Math.cos(a);
  const sinB = Math.sin(b), cosB = Math.cos(b);
  return points.map((p) => {
    const y1 = p.y * cosA + p.z * -sinA;
    const z1 = p.y * sinA + p.z * cosA;
    const x2 = p.x * cosB + z1 * sinB;
    return { x: x2, y: y1, z: z1 * cosB - p.x * sinB };
  });
}

2.3 透视投影：从 3D 空间到 2D 屏幕

最后的数学运算将旋转后的 3D 坐标转换为 2D 屏幕位置。该库使用一种简化但高效的投影模型，基于深度计算缩放因子和不透明度因子，透视深度参数等于球体半径的两倍：

$$\text{‘{’}per{‘}’} = \frac{‘{’}2 \cdot \text{‘{’}depth{‘}’}{‘}’}{‘{’}2 \cdot \text{‘{’}depth{‘}’} + z{‘}’} = \frac{‘{’}4R{‘}’}{‘{’}4R + z{‘}’}$$

不透明度（alpha）因子使用二次关系并带有偏置调整：

$$\text{‘{’}alpha{‘}’} = \text{‘{’}clamp{‘}’}\left(\text{‘{’}per{‘}’}^2 - 0.25, ; 0, ; 1\right)$$

完整的投影管线总结如下：

$$\boxed{‘{’}\begin{‘{’}aligned{‘}’} \text{‘{’}per{‘}’}_i &= \frac{‘{’}2 \cdot \text{‘{’}depth{‘}’}{‘}’}{‘{’}2 \cdot \text{‘{’}depth{‘}’} + z_i{‘}’} \ \text{‘{’}scale{‘}’}_i &= \text{‘{’}per{‘}’}_i \ \text{‘{’}alpha{‘}’}_i &= \min\left(1, ; \max\left(0, ; \text{‘{’}per{‘}’}_i^2 - 0.25\right)\right) \ P_i^{‘{’}\text{‘{’}2D{‘}’}{‘}’} &= \left(x_i \cdot \text{‘{’}scale{‘}’}_i, ; y_i \cdot \text{‘{’}scale{‘}’}_i, ; \text{‘{’}scale{‘}’}_i, ; \text{‘{’}alpha{‘}’}_i\right) \end{‘{’}aligned{‘}’}{‘}’}$$

TypeScript 实现精确地反映了这一数学公式：

export function project(
  points: { x: number; y: number; z: number }[],
  depth: number,
): ProjectedTag[] {
  const d2 = 2 * depth;
  return points.map((p) => {
    const per = d2 / (d2 + p.z);
    const alpha = Math.min(1, Math.max(0, per * per - 0.25));
    return { x: p.x, y: p.y, z: p.z, scale: per, alpha };
  });
}

3. 架构与模块设计

该代码库通过刻意分离数学计算、渲染编排和用户交互处理，体现了清晰的软件架构。

3.1 纯数学引擎：src/core/

3.2 双渲染系统：Canvas + DOM

最显著的创新之一是其 双渲染系统，使用 Canvas 2D API 渲染文本和图像，使用 DOM 叠加层渲染 SVG、HTML、视频和 Web Components。

flowchart TB
    subgraph "标签类型与渲染器"
        direction LR
        TEXT["📄 文本标签"]
        IMG["🖼️ 图像标签"]
        SVG_TAG["🎨 SVG 标签"]
        HTML_TAG["🌐 HTML 标签"]
        VIDEO["🎬 视频标签"]
        ELEMENT["🔧 元素标签"]
    end

    subgraph "渲染器选择"
        CANVAS["Canvas 2D API
✅ 文本
✅ 图像"]
        DOM["DOM 叠加层
✅ SVG
✅ HTML
✅ 视频
✅ Web Components"]
    end

    TEXT --> CANVAS
    IMG --> CANVAS
    SVG_TAG --> DOM
    HTML_TAG --> DOM
    VIDEO --> DOM
    ELEMENT --> DOM

    style CANVAS fill:#0f3460,stroke:#e94560,color:#fff
    style DOM fill:#533483,stroke:#e94560,color:#fff

4. 性能特征

4.1 计算复杂度

4.2 内存效率

对于 (N = 100) 个标签，总数字状态约为 (100 \times (3 + 5) \times 8 = 6,400) 字节 —— 不到 7KB 的浮点数。

4.3 打包体积

5. 多模态内容：六种标签类型

6. 与 cong-min/TagCloud 的对比

7. 实战使用指南

7.1 基础纯文本云

import { TagCloud } from "@xingwangzhe/tags-cloud";

const container = document.getElementById("cloud")!;
new TagCloud(container, {
  tags: ["TypeScript", "React", "Vue", "Svelte", "Node.js", "Bun", "Rust"],
  radius: 250,
  spinY: 0.12,
  color: "#e0e0e0",
  fontSize: 16,
});

7.2 多模态云

new TagCloud(container, {
  tags: [
    "TypeScript",
    { type: "image", src: "/avatar.webp", width: 40, height: 40 },
    { type: "svg", content: `<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/></svg>`, width: 48, height: 48 },
    { type: "video", src: "/demo.mp4", width: 120, height: 68 },
  ],
  radius: 300,
  spinY: 0.15,
  onTagClick(item) { console.log("Clicked:", item); },
});

7.3 生命周期管理

const cloud = new TagCloud(container, { tags, spinY: 0.2 });
cloud.setTags(["New", "Set", "Of", "Tags"]);
cloud.pause();
cloud.resume();
cloud.destroy();

8. 结论：数学作为渲染引擎

@xingwangzhe/tags-cloud 有力地证明，软件中最强大的渲染引擎不是 GPU、不是着色器编译器、也不是框架 —— 而是 数学。通过将 3D 标签云可视化问题分解为三个纯数学运算 —— 斐波那契球面分布、旋转矩阵乘法和透视投影 —— 该库实现了与基于 WebGL 的方案在视觉上难以区分的效果，同时无需任何其复杂性、硬件依赖或打包体积负担。

该项目对开源生态系统的贡献体现在三个方面。架构上，它证明了混合 Canvas/DOM 渲染器能够在 3KB 的包中同时提供性能和多功能性。数学上，它提供了基础 3D 图形算法的干净、文档完善的实现。实践上，它为开发者提供了一个即插即用的组件，用于创建支持富媒体、TypeScript 类型安全和移动端就绪交互的 3D 标签云 —— 所有这一切都不需要添加任何依赖。

本文结束 —— 基于对 @xingwangzhe/tags-cloud v0.9.0 的源代码分析