如何在 Bootstrap 折叠组件中单击即加载 NGL 3D 分子可视化

本文解决 bootstrap collapse 元素内嵌 ngl 3d 查看器需双击才能初始化的问题，核心在于确保 dom 容器渲染完成后再创建 stage 实例。

在使用 Bootstrap 的 .collapse 组件配合 NGL（如 ngl.min.js）构建交互式 3D 分子结构查看器时，一个常见陷阱是：用户首次点击“Show 3D”后，3D 视图未立即渲染，需再次点击才生效。根本原因在于——onclick 事件触发时，折叠区域（#show_0）虽已开始展开，但其内部容器 #viewport_0 尚未完成 DOM 插入或尺寸计算，导致 NGL.Stage 初始化失败或渲染异常。

虽然 setTimeout 是快速验证方案，但依赖固定延迟（如 setTimeout(..., 0)）并不健壮——它无法保证 DOM 回流/重绘已完成，尤其在低性能设备或复杂页面中仍可能失效。更可靠的解法是监听折叠完成事件，并在回调中安全初始化 NGL。

✅ 推荐解决方案：利用 Bootstrap Collapse 的 shown.bs.collapse 事件

Bootstrap 4+ 为 .collapse 提供了原生事件钩子。shown.bs.collapse 在折叠内容完全显示且 CSS 过渡结束后触发，此时 #viewport_0 已稳定存在于 DOM 中并具备有效尺寸：

  
    Show 3D
  



  
    
      
    
  

// 在页面加载完成后绑定事件（确保 Bootstrap JS 已就绪）
document.addEventListener('DOMContentLoaded', function () {
  const collapseElement = document.getElementById('show_0');

  collapseElement.addEventListener('shown.bs.collapse', function () {
    // 此时 #viewport_0 已渲染完成，可安全初始化 NGL
    const viewportId = 'viewport_0';
    const pdbUrl = 'https://alphafold.ebi.ac.uk/files/AF-P08047-F1-model_v4.pdb';

    // 避免重复初始化（例如用户多次展开）
    if (window.nglStages && window.nglStages[viewportId]) {
      return;
    }

    const stage = new NGL.Stage(viewportId, { backgroundColor: 'white' });

    // 缓存实例便于后续管理（如销毁、重载）
    if (!window.nglStages) window.nglStages = {};
    window.nglStages[viewportId] = stage;

    stage.loadFile(pdbUrl).then(function (component) {
      component.addRepresentation("cartoon", { color: 'white' });
      component.autoView();
      stage.render(); // 显式触发首帧渲染（增强兼容性）
    }).catch(err => {
      console.error('Failed to load PDB:', err);
      document.getElementById(viewportId).innerHTML = 
        '
❌ Failed to load 3D structure. Please check the URL or network.
';
    });
  });
});

⚠️ 注意事项与最佳实践

• 不要移除 data-toggle 和 data-target：它们是 Bootstrap 控制折叠逻辑的核心，仅需剥离内联 onclick。
• 确保脚本执行时机：将上述 JS 放在 底部，或包裹在 DOMContentLoaded 中，避免因 Bootstrap JS 未加载而监听失败。
• 防重复初始化：通过全局缓存 window.nglStages 避免用户反复展开/收起时重复创建 Stage（NGL 实例不可复用，重复创建会泄漏内存）。
• 错误处理必不可少：网络失败、PDB 格式错误、CORS 限制等均可能导致 loadFile() 拒绝 Promise，应提供降级 UI 提示。
• 移动端适配建议：若需支持触摸设备，可额外监听 click 事件并调用 collapseElement.collapse('show')，但优先使用 Bootstrap 原生事件以保持一致性。

通过事件驱动而非时间驱动的方式初始化 NGL，既符合 Web 标准，又保障了跨环境稳定性——真正实现「单击即见 3D」的流畅用户体验。