Cytoscape.js 图论库实战指南：从一行代码建图到构建、测试与发布
项目地址: https://gitcode.com/gh_mirrors/cy/cytoscape.js Cytoscape.js 是面向可视化与分析场景的图论（网络）JavaScript 库，既能服务端在 Node.js 中做图分析，也能在浏览器中渲染可交互图。本文以项目 README.md 为主线，结合仓库源码，完整讲解从一行代码初始化图实例、理解内置布局与渲染架构，到执行构建、测试、发布全流程的实操方案，帮助读者直接上手二次开发与集成。
项目定位：图论建模与可视化的一体化库
Cytoscape.js 的核心定位是"fully featured graph theory library"：它既包含一套完整的图论数据模型（图、节点、边、复合节点），又提供一个可选渲染器用于展示交互式图。官方描述的使用场景包括生物关系数据、社交网络等关系型数据的建模与可视化，无论是 Node.js 服务端的图分析，还是富交互的 Web 界面，都适用。
从入口源码 src/index.mjs 可以看到库的最小设计：
let cytoscape = function( options ){
if( options === undefined ){
options = {};
}
if( is.plainObject( options ) ){
return new Core( options ); // 传入配置对象 => 创建图实例
} else if( is.string( options ) ){
return extension.apply( extension, arguments ); // 传入字符串 => 扩展注册
}
};
也就是说，cytoscape(options) 与 cytoscape(extensionName, ...args) 是两条并行的调用路径：前者用于实例化一个图（Core），后者用于注册第三方扩展（如 cytoscape.use(...) 模式，见 src/index.mjs）。
快速上手：一行代码创建图实例
README 给出了最核心的入门姿势，仅一行即可启动：
var cy = cytoscape({ elements: myElements, container: myDiv });
其中 elements 提供图数据，container 指定承载渲染的 DOM 元素。从 src/core/index.mjs 的 Core 构造函数实现看，初始化时会自动做如下处理：
- 容器兼容：允许传入 jQuery 包装对象（
container[0]为原生元素时自动解包，见 src/core/index.mjs）； - 默认布局与渲染器：
options.layout默认grid（有容器时）或null，options.renderer默认canvas或null，从而实现有界面渲染与无界面（headless）分析的统一； - 初始化参数体系：支持
zoom、pan、minZoom、maxZoom、zoomingEnabled、panningEnabled、boxSelectionEnabled、autolock、autoungrabify、autounselectify、multiClickDebounceTime等选项（src/core/index.mjs），默认缩放区间为1e-50到1e50； - 异步数据加载：
style与elements均支持 Promise，通过Promise.all并行加载后再执行ready/done回调（src/core/index.mjs）。
此外还支持 headless: true 模式：在不传入容器时，head 判定为假，默认使用 null 渲染器，适合在 Node.js 端进行纯图算法计算。
示例：可视化东京地铁网络
README 以东京地铁站点网络为例展示渲染效果，项目文档目录下保留了完整示例：documentation/demos/tokyo-railways/（含 index.html、style.css、tokyo-railways.js、tokyo-railways.cycss、tokyo-railways.json），对应效果图如下：
这类 demo 的通用做法是：data.json（或内联的 elements）提供节点/边数据，style.css 与样式表（.cycss 或 JSON 样式）定义视觉外观，code.js 完成 cytoscape({ container, elements, style }) 的装配。更多示例可参考 documentation/demos 目录下的众多可运行用例（如 compound-nodes、edge-types、cose-layout 等）。
内置能力总览：布局、渲染器与图算法
README 指向官方文档介绍功能，而仓库源码可以更精确地佐证内置能力清单：
内置布局（src/extensions/layout/index.mjs）：breadthfirst、circle、concentric、cose、grid、null、preset、random 共 8 种，覆盖层次、环形、同心圆、力导向、网格、随机等常用布局需求。
内置渲染器（src/extensions/renderer/index.mjs）：null（无头渲染）、base（基础渲染基座，负责坐标计算、节点形状、箭头、标签等）、canvas（默认 Canvas 渲染器）；渲染器内部还包含纹理缓存（src/extensions/renderer/canvas/texture-cache-defs.mjs）与 WebGL 实现（见 src/extensions/renderer/canvas/webgl 及调试页 debug/webgl/index.html）。
图算法集合（src/collection/algorithms）：a-star、bellman-ford、dijkstra、bfs-dfs、floyd-warshall、kruskal、karger-stein、page-rank、tarjan-strongly-connected、hopcroft-tarjan-biconnected、hierholzer、markov-clustering、k-means、k-medoids、affinity-propagation 等 20 个算法模块，覆盖最短路径、连通性、中心性、聚类、随机算法等图论分析需求，直接通过集合 API 调用即可。
扩展机制方面，src/extensions/index.mjs 将布局与渲染器统一登记为扩展，第三方扩展可沿用同一套注册体系。
文档与下载
完整 API 文档与各版本下载入口位于项目官网（README 中指向 https://js.cytoscape.org）。仓库内的 documentation/ 目录保留了文档生成源（docmaker.mjs、docmaker.json）与全部 Markdown 文档（如 documentation/md/style.md、documentation/md/events.md、documentation/md/selectors.md），并随构建产出 documentation/js/cytoscape.min.js 供文档页使用。
构建依赖与构建指令
README 明确要求先安装 node 与 npm，然后在仓库根目录执行 npm install 后再使用 npm run。本仓库 package.json 当前版本为 3.35.0-unstable，engines 声明 node>=0.10。
主要构建目标（npm run <target>）汇总如下：
| 目标 | 作用 |
|---|---|
build | 执行全部构建（umd、min、cjs、esm） |
build:min | 非压缩 UMD 构建（打包依赖，适合简单 HTML 页面、新手） |
build:umd | UMD（cjs/amd/globals）构建 |
build:esm | ESM（ES 2015 模块）构建 |
clean | 清空 build 目录 |
docs | 构建文档到 documentation |
release | 构建全部发布产物 |
watch | 快速增量构建（含 sourcemap、无 babel），适合在 debug/index.html 上调试，自动在 http://localhost:8080（或首个可用端口）启动服务并 livereload |
watch:babel | 带 babel 的增量构建，适合性能测试或老旧浏览器测试 |
watch:umd | 增量构建生产版 UMD bundle（无 sourcemap、带 babel），供其他项目通过 "cytoscape": "file:./path/to/cytoscape" 引用测试，不启动 HTTP 服务 |
dist | 更新 npm 等使用的分发 js 文件 |
构建实现由 rollup.config.mjs 承担：入口统一为 ./src/index.mjs，输出 5 个产物——build/cytoscape.umd.js、build/cytoscape.min.js（terser 压缩）、build/cytoscape.esm.mjs、build/cytoscape.esm.min.mjs、build/cytoscape.cjs.js，并通过环境变量 FILE、SOURCEMAPS、BABEL、NODE_ENV 控制单目标构建与调试配置。发布到 npm 时，package.json 的 exports 字段将 import/require 分别映射到 ESM 与 CJS 产物，unpkg 与 jsdelivr 指向 dist/cytoscape.min.js。
测试体系
README 说明：默认测试脚本直接针对源码运行，也可对构建产物运行测试；库可在 node>=6 上构建，bundle 测试兼容 node>=0.10。
npm test # 运行全部测试与 lint
npm run test:js # mocha 针对源码公开 API 的测试
npm run test:js -- -g "my test name" # 仅运行匹配用例
npm run test:build # 对构建产物运行公开 API 测试（需先 npm run build）
npm run test:build -- -g "my test name"
npm run test:modules # 对私有内部 API 运行单元测试
npm run lint # eslint 检查 src 下源码
npm run benchmark # 运行全部基准测试
npm run benchmark:single # 仅运行 benchmark/single 指定的套件
测试代码集中在 test 目录，覆盖集合算法、遍历、数据、样式、选择器、事件、核心初始化、导出等模块（如 test/collection-algorithms.mjs、test/core-export.mjs）；test/modules 下存放内部模块单测；benchmark/ 目录提供各类基准（如 benchmark/dijkstra.js、benchmark/selector-filter.js）。Playwright 渲染测试配置见 playwright.config.js 与 playwright-tests/renderer.spec.js。
发布流程
README 给出的发布节奏是：功能版本每月发布一次，补丁版本每周发布一次，以便快速吸收第一方与第三方贡献。发布前需在 issue 里程碑中规划好对应版本的议题，bug 修复需同时合入 master 与 unstable 分支；若补丁版与功能版并发发布，应先发补丁版，并等待 5 分钟再发功能版，避免 Zenodo 收录异常。
补丁版本：进入 GitHub Actions 的 Release 工作流 → "Run workflow" → Release type 选择 patch → 运行 → 关闭对应里程碑。
功能版本：同样通过 Release 工作流选择 feature 运行，关闭里程碑后还需在博客发布版本公告。
注意事项：
- "Use workflow from" 只影响 workflow YML 文件的来源分支，master/unstable 上的 workflow 通常一致，无需特别选择；
- 发布流程自身会按发布类型检出正确分支，无需手动选分支；
- 若
npm publish在发布成功后失败（如 npm 注册表瞬时错误），应使用 "Re-run failed jobs" 重跑失败的 job，不要重新触发一次发布——因为版本号已提交并推送，重新触发会再次 bump 版本，导致上一个版本遗留未发布。
贡献与引用
若希望参与贡献（技术角色如功能与测试，或非技术角色如文档与外联），README 建议通过 GitHub Discussion 联系维护团队；PR 的具体操作规范见 CONTRIBUTING.md。
在论文中引用 Cytoscape.js 时，请引用 Oxford Bioinformatics 论文：
Cytoscape.js: a graph theory library for visualisation and analysis Franz M, Lopes CT, Huck G, Dong Y, Sumer O, Bader GD Bioinformatics (2016) 32 (2): 309-311
项目同时有 2016 年原始论文与 2023 年更新论文，可在 PubMed 检索到对应摘要。
Roadmap 与版本规划
未来版本计划在 GitHub issue tracker 的 milestones 中公开，可通过里程碑查看当前规划的发布内容，这既是了解新功能动向的入口，也是参与版本规划讨论的地方。结合 package.json 的版本号（当前 3.35.0-unstable）可以判断，仓库遵循"功能版月更、补丁版周更"的快节奏迭代策略。
小结
从 README 的核心信息出发，结合源码可以看出 Cytoscape.js 的完整工作链路：cytoscape(options) 创建 Core → 加载元素与样式 → 默认 grid 布局 + canvas 渲染器展示 → 通过集合 API 调用内置图算法进行分析；开发侧则通过 rollup.config.mjs 产出 UMD/ESM/CJS 多格式产物，配合 package.json 的脚本完成构建、测试与发布。无论是要快速集成一个可交互网络图，还是在 Node.js 端做图论计算，亦或是基于其扩展机制开发自定义布局与渲染器，本文所述流程都可以作为直接上手的起点。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
