本文介绍如何解决 litstudy 使用 pyvis 渲染网络图时因禁用交互（interactive=False）导致节点重叠的问题，通过定制 pyvis 模板并关闭物理引擎实现布局冻结，获得清晰、可复现的静态图输出。
本文介绍如何解决 litstudy 使用 pyvis 渲染网络图时因禁用交互（`interactive=false`）导致节点重叠的问题，通过定制 pyvis 模板并关闭物理引擎实现布局冻结，获得清晰、可复现的静态图输出。
litstudy 默认调用 pyvis 进行网络可视化，其 plot_network(..., interactive=True) 会启动带力导向布局（force-directed layout）的交互式 HTML 页面，节点经物理模拟后自动排布，视觉效果良好但无法固定；而设为 interactive=False 时，pyvis 会跳过物理计算直接渲染，导致所有节点默认堆叠在画布原点（0,0），失去可读性。
根本原因在于：静态模式下 pyvis 并未执行布局计算，也未保存或复用交互模式下的最终坐标。因此，单纯切换参数无法保留布局——必须让图在完成稳定化（stabilization）后主动冻结物理引擎，再导出为静态视图。
✅ 推荐解决方案：定制 pyvis 模板 + 注入冻结逻辑
该方案不修改 litstudy 核心逻辑，而是通过扩展 pyvis 的 HTML 模板，在图稳定后立即关闭物理引擎，从而保留高质量布局并禁用拖拽/缩放等交互行为。
步骤 1：定位并备份 pyvis 模板文件
运行以下代码获取模板路径：
import pyvis print(pyvis.__file__)
进入其安装目录 → templates/ 文件夹，找到 template.html（通常位于 site-packages/pyvis/templates/template.html）。将其复制到本地安全路径，例如：C:/Users/YourName/Documents/pyvis_static_template/
步骤 2：修改 template.html，注入布局冻结逻辑
在 <script></script> 标签内、network = new vis.Network(...) 初始化之后，找到 network.once("stabilizationIterationsDone", ...) 或 network.on("stabilizationIterationsDone", ...) 块（若无则手动添加），插入以下关键语句：
network.once("stabilizationIterationsDone", function() {
// 冻结物理引擎，锁定节点位置
network.setOptions({ physics: false });
// （可选）隐藏加载提示栏，提升视觉整洁度
document.getElementById('loadingBar')?.style.display = 'none';
});
⚠️ 注意：确保该逻辑仅在
once（单次触发）或on（首次稳定后）中执行，避免重复调用影响性能。
步骤 3：在 litstudy 绘图时指定自定义模板
修改你的绘图代码，在 plot_network() 调用前显式设置模板路径：
import litstudy
from litstudy.network import plot_network
# 构建网络（保持原有逻辑）
coauthor_network = litstudy.build_coauthor_network(total_docs_found)
# 创建 PyVis 实例并指定模板
v = plot_network(
coauthor_network,
max_node_size=75,
interactive=True # 关键：仍需设为 True 才能触发 stabilization
)
# 指向你修改后的模板
template_dir = r"C:/Users/YourName/Documents/pyvis_static_template"
v.set_template_dir(template_dir)
# 保存为静态 HTML（无交互、布局固定）
v.show("coauthor_network_static.html")
✅ 效果：浏览器打开生成的 HTML 文件时，图将短暂运行物理布局 → 自动稳定 → 立即冻结 → 停止所有运动与交互，呈现完全静态、节点分离、结构清晰的终态图。
? 补充说明与最佳实践
为何不直接用
interactive=False？
因其绕过整个布局引擎，等价于“零初始化”，无坐标计算，故必然重叠。本方案本质是“借力交互模式完成布局，再一键冻结”，兼顾质量与静态性。导出为图片？
若需 PNG/SVG，可在冻结后的 HTML 页面中使用浏览器「打印为 PDF」→ 再转图；或借助selenium自动截图（需额外配置）。可移植性提醒：
自定义模板路径应使用绝对路径，并确保部署环境存在该文件。生产脚本中建议加入os.path.exists()校验。升级兼容性：
pyvis 版本更新可能调整模板结构，建议锁定pyvis==0.3.1或定期验证template.html中事件钩子语法。
通过以上方法，你即可在 litstudy 工作流中稳定产出学术级静态合作网络图——布局专业、分析友好、发表就绪。
