本文解决 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 中并具备有效尺寸：
<!-- 修改 onclick 为 data-toggle + 事件监听 -->
<div class="row">
<div class="col"
data-toggle="collapse"
data-target="#show_0"
id="_show_0">
<b>Show 3D</b>
</div>
</div>
<div id="show_0" class="collapse">
<div class="row">
<div class="col">
<div id="viewport_0" style="width:100%; height:800px;"></div>
</div>
</div>
</div>// 在页面加载完成后绑定事件（确保 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 =
'<p class="text-danger">❌ Failed to load 3D structure. Please check the URL or network.</p>';
});
});
});⚠️ 注意事项与最佳实践
- 不要移除 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」的流畅用户体验。
