用途:在浏览器(原生 JS、React、Vite)中渲染 Neo4j 图,支持自定义交互、渲染与数据形状,可将 driver.executeQuery 结果可视化为交互式图,并接入缩放、平移、拖拽、点击、悬停、套索、框选等交互。若只需默认 Neo4j 样式的嵌入式图视图,应改用 @neo4j-ndl/react 的 GraphVisualization;Python/Jupyter 可视化、Cypher 编写、驱动配置、GDS、GraphQL 等场景应使用对应技能。
安装:npm install @neo4j-nvl/base(核心必需);npm install @neo4j-nvl/interaction-handlers(原生 JS 标准交互,可选);npm install @neo4j-nvl/react(React 封装,可选)。@neo4j-nvl/react 建议搭配 React 19。@neo4j-nvl/layout-workers 为传递依赖,不要直接安装。官方脚手架见 https://github.com/neo4j-devtools/nvl-boilerplates。许可证为 Neo4j Visualization Library License,仅限配合 Neo4j 产品使用。
主要能力:NVL 构造函数为 new NVL(frame, nvlNodes?, nvlRels?, options?, callbacks?)。渲染器可选 'canvas'(默认,约 1000 节点,支持标题、图标、箭头与精确命中测试)或 'webgl'(10 万+ 节点,2.0 中不支持标题),可用 setRenderer 运行时切换。2.0 的 GPU 渲染与力导向物理引擎需要 WebGL2,不可用时回退 Canvas,可用 disableWebGL: true 显式禁用。支持力导向与层次布局、clusterBy 聚类、节点位置更新、图元素增删改、getHits 手动命中测试、saveToFile/saveToSvg 导出。
使用方式:容器必须显式设置宽和高,否则高度为 0 导致图不可见。原生 JS 用 NVL 加 interaction-handlers 组合交互,每个处理器通过 updateCallback 注册回调并需 destroy();React 可用 InteractiveNvlWrapper(预接全部交互,通过 mouseEventCallbacks 开关)或 BasicNvlWrapper(不预接交互,ref 暴露全部 NVL 方法)。接入驱动结果需使用 nvlResultTransformer 获取 { nodes, relationships },不能直接传 EagerResult。
限制:WebGL 渲染器不支持标题;聚类回调仅针对聚类外壳空白区域,节点与关系命中优先;crossClusterRelationshipMultiplier 为实验性且取值 0..1;1.x 迁移需将 layout/layoutOptions 移入 nvlOptions,onZoom 改为 onZoomAndPan,并移除 intelWorkaround 与 Cytoscape 相关设置。销毁时需调用 nvl.destroy(),原生交互处理器也需逐个 destroy()。其余细节暂未提供。