简介这份前端项目资料围绕3Dmol.js展开面向希望在浏览器中呈现化学结构的前端开发者、科学教育工作者及化学信息学学习者重点解决PDB、MOL、SDF等分子数据的解析与三维展示问题。zip压缩包整体约136.09MB文件总数与主要文件类型暂无明细需以实际解压目录为准。已有342人学习说明其在分子可视化入门与项目集成场景中具有一定参考价值。内容涵盖WebGL渲染基础、分子坐标与键结构建模、旋转平移缩放及原子高亮等交互API也涉及动画更新、颜色与材质定制、与HTML/CSS及常规前端库的整合方式针对较大分子还提到Web Workers预处理与响应式适配等性能与体验要点。读者可据此理解3Dmol.js在前端项目中的组织方式并迁移到教学演示、结构浏览或科研可视化页面中。1. 分子结构可视化前端项目的实际难点接手一个分子结构展示的前端项目时最容易犯的错误是拿 three.js 拼个球棍模型就交付——球画出来了键角是错的侧链方向全歪导出的数据和原始结构对不上。这份压缩包走的是另一条路把 3Dmol 这套分子可视化能力封装成一个可直接运行的前端项目骨架打开就是一个能旋转、能缩放、能按链上色、能点原子看属性的视口。它真正处理的是「结构数据怎么在浏览器里被正确解读」涉及选择器语法、格式解析和领域渲染规则模型转得漂不漂亮并不是重点。适合手上有 PDB/SDF 文件、需要做成网页展示的前端也适合做结构审阅、教学演示的开发者前提是你写 HTML 和 JS 不顺但不要求懂 WebGL、着色器或矩阵变换。2. 从空 div 到能转的分子渲染管线与最小可运行页2.1 这套渲染管线替你做了什么先讲清楚它替前端承担了哪些工作后面调试时才有方向感。3Dmol 的底层是 WebGL 加一套自带的结构解析器喂进去一份 PDB 文本它先把ATOM、HETATM、HELIX、SHEET这些记录行解析成原子对象数组每个对象带坐标、元素符号、残基名、残基号、链标识、温度因子然后按共价半径和键长阈值自动连键最后交给 WebGL 绘制。这个流程里有几件普通 3D 引擎做不了的事。其一元素符号的大小写有严格语义CA在 PDB 里是 α 碳碳元素Ca才是钙原子解析器必须区分大小写自己写正则很容易在这里出错。其二二级结构信息藏在HELIX、SHEET记录里cartoon 模式画出来的螺旋和折叠片依赖这些行光有原子坐标是画不出来的。其三残基和链是逻辑分组选择器{chain:A, resi:12}能命中一整段这层索引也要引擎预先建好。所以选型判断很直接如果你的需求只是「展示一个三维物体」three.js 更轻只要涉及「按残基高亮、按二级结构上色、点原子出信息」用现成的分子引擎能省掉几周时间。2.2 最小可运行页面四步走完一条链路整个渲染链路可以压缩成四步建 viewer、加载 model、设 style、调 render。下面这段是把压缩包里的入口页精简到最小后的骨架可以直接另存为index.html跑起来。!DOCTYPE html html langzh-CN head meta charsetutf-8 / meta nameviewport contentwidthdevice-width, initial-scale1 / title分子结构查看器/title !-- 库文件放本地避免首屏依赖外部网络 -- script src./lib/3Dmol-min.js/script style html, body { margin: 0; height: 100%; } /* 容器必须有确定高度否则 canvas 高度为 0 */ #viewport { width: 100%; height: 520px; position: relative; } /style /head body div idviewport/div script const el document.getElementById(viewport); // 1. 建 viewerbackgroundColor 是画布底色antialias 开抗锯齿 const viewer $3Dmol.createViewer(el, { backgroundColor: white, antialias: true }); // 2. 加载结构文件fetch 走同源路径 fetch(./data/sample.pdb) .then(res { if (!res.ok) throw new Error(HTTP res.status); return res.text(); }) .then(text { // 3. 第二个参数是格式名必须和数据真实格式一致 const model viewer.addModel(text, pdb); // 4. 默认样式细棍 小球适合先确认坐标没错 viewer.setStyle({}, { stick: { radius: 0.15 }, sphere: { scale: 0.25 } }); viewer.zoomTo(); // 根据模型包围盒自动调整相机 viewer.render(); // 提交一帧 console.log(原子数, model.selectedAtoms({}).length); }) .catch(err { el.innerHTML p stylepadding:16px结构加载失败 err.message /p; }); /script /body /html代码后要解释几个参数因为后面的问题大多出在参数上。createViewer的第二个参数是全局配置对象。backgroundColor决定画布底色白色适合截图贴文档深色适合投影演示antialias打开会带来抗锯齿代价是在低端显卡上帧率下降分子原子数超过两三万时可以先关掉再测。addModel的第二个参数是格式标识这个参数写错不会报错只会给你一个空模型或者错乱的坐标属于最难发现的一类问题。常见取值有pdb、sdf、mol2、xyz、cif写错大小写也不认。setStyle的第一个参数是选择器传空对象{}表示「所有原子」。stick.radius控制棍的粗细默认值约 0.25缩到 0.15 更适合整体观察sphere.scale是相对范德华半径的缩放系数0.25 到 0.3 之间视觉上最舒服。zoomTo内部按当前所有模型的包围盒计算相机距离所以它必须在addModel之后调用。如果代码顺序颠倒相机停在初始位置看到的就是一个偏移到屏幕外或者巨大无比的结构。render是显式提交3Dmol 不会自动重绘任何改动样式、增删模型的调用之后都要补一次render否则画面不变。2.3 容器尺寸、像素比与 resize 的联动这一节是新手最容易跳过、也最容易在真机上出错的部分。canvas 的尺寸由容器尺寸决定而容器尺寸由 CSS 决定。如果#viewport只有width: 100%没有高度或者父级是display: flex但没给flex: 1那么元素高度为 0WebGL 画布初始化后不可见控制台还一片安静。移动端还有一层设备像素比。高分屏上 CSS 像素和物理像素不是一比一如果库内部拿不到正确的比例画面会糊。常见做法是启动前把容器尺寸和像素比都确认一遍const el document.getElementById(viewport); const viewer $3Dmol.createViewer(el, { backgroundColor: white }); // 窗口变化后必须重算画布缓冲尺寸 let rafId null; window.addEventListener(resize, () { if (rafId) cancelAnimationFrame(rafId); rafId requestAnimationFrame(() { viewer.resize(); // 重新读取容器宽高重建画布缓冲 viewer.render(); // 重绘一帧否则会出现黑边或拉伸 }); });viewer.resize()只做一件事把 canvas 的宽高重新对齐容器。但它不会重新调整相机所以窗口从竖屏切到横屏时结构可能跑出可视区域稳妥的做法是在 resize 回调里补一次viewer.zoomTo()。用requestAnimationFrame包一层是因为 resize 事件在拖拽窗口时每秒能触发几十次每次都重建 WebGL 缓冲区会明显卡顿节流到一帧一次就顺了。提示容器用position: relative加上固定高度是最稳的组合如果用百分比高度必须保证从html、body到容器这条链上每一级都有确定高度否则高度会塌陷。3. 结构文件怎么进页面PDB、SDF、XYZ 的加载与格式判定3.1 四种格式的能力差异与选型压缩包里的数据目录一般会混着几种格式选错格式的代价比想象中大。它们的核心差异在「是否含键信息」「是否含二级结构」「是否含氢原子」这三件事上。格式键连接信息二级结构典型用途解析器名PDB部分由距离推断有靠 HELIX/SHEET 记录大分子、蛋白质pdbSDF / MOL有显式键表无小分子、配体sdfMOL2有含键级与原子类型无对接结果、力场数据mol2XYZ无只含坐标和元素无量化计算结果xyz实践中的判断规则蛋白质、核酸走 PDB小分子配体、化合物走 SDF从对接软件导出的构象走 MOL2从量化程序导出的轨迹走 XYZ。用 XYZ 加载蛋白质会让引擎完全靠距离阈值连键长链结构上会出现一堆莫名其妙的伪键看起来像「分子被黏在一起」这属于格式选型错与渲染无关。还有一个常被忽略的点PDB 里可能存在多个MODEL记录表示同一结构的多帧构象。默认解析只取第一帧如果要看动态构象需要额外传参把多帧都读进来再逐帧切换否则你会以为文件损坏了。3.2 本地文件加载与用户上传两条通路线上项目不可能只读固定路径的文件通常要支持用户拖一份结构文件进来。两条通路的代码结构不同但最终都汇到addModel这一个函数上。const viewer $3Dmol.createViewer(document.getElementById(viewport), { backgroundColor: white }); // 通路一从服务端或静态目录拉取 async function loadFromUrl(url, format) { const res await fetch(url); if (!res.ok) throw new Error(HTTP res.status); const text await res.text(); return mountModel(text, format); } // 通路二用户选择本地文件 function loadFromFile(file) { return new Promise((resolve, reject) { const reader new FileReader(); reader.onload () { // 格式从扩展名推断兜底用 pdb const ext file.name.split(.).pop().toLowerCase(); const fmtMap { pdb: pdb, sdf: sdf, mol: sdf, mol2: mol2, xyz: xyz }; try { resolve(mountModel(reader.result, fmtMap[ext] || pdb)); } catch (e) { reject(e); } }; reader.onerror () reject(new Error(文件读取失败)); reader.readAsText(file); // 结构文件都是纯文本不要用 readAsArrayBuffer }); } function mountModel(text, format) { viewer.removeAllModels(); // 多次加载必须先清空否则模型叠加 viewer.removeAllSurfaces(); const model viewer.addModel(text, format); const count model.selectedAtoms({}).length; if (count 0) throw new Error(解析结果为空检查格式名是否匹配); viewer.setStyle({}, { stick: { radius: 0.15 }, sphere: { scale: 0.25 } }); viewer.zoomTo(); viewer.render(); return model; }说明几点。removeAllModels()不能省。用户连续拖两个文件进来时如果不清空两个结构会叠在同一个场景里看起来像「残基翻倍了」排查半天才发现是没清理。removeAllSurfaces()要一起调因为表面网格是独立于模型挂载的只删模型不删表面会留下一层半透明外壳飘在空气里。readAsText而不是readAsArrayBuffer这些格式全是文本用二进制读会得到一串乱码字符addModel解析失败后返回空模型报错信息还极其含糊。selectedAtoms({})用来做一次体检。它返回模型里所有原子的数组长度为零说明解析器一个原子都没认出来最常见的三个原因是格式名写错、文件编码是 UTF-16、文件开头有 BOM 或者多余的空行。3.3 解析失败的三种典型信号解析失败在 3Dmol 里几乎不抛异常它更倾向于「安静地给你一个空结果」所以必须自己加判断。三种典型信号和处理方式第一种addModel返回的对象selectedAtoms({})长度为 0。这类多半是格式名和内容不符比如把 SDF 当成 PDB 喂进去。解决方向是打印文本前 80 个字符看一眼PDB 以HEADER、ATOM、HETATM开头SDF 第一行是分子名、第四行是counts行、以M END结尾。第二种原子数正常但画面只有零星几个球。这通常是元素符号列对不上解析器把不认识的符号当成默认元素或者坐标列被位移。PDB 的列位是强制的X 坐标固定在第 31 到 38 列如果文件被某个脚本重排过列宽坐标会整体错位画出来是一团扁平的乱麻。第三种结构画出来了但是断成好几截。多链蛋白在 PDB 里是连续记录的如果中间有缺失残基或者TER记录被误删引擎会按链断开处理。这种不是 bug是数据本身如此需要在 UI 上说明「存在缺失残基」而不是反复调渲染参数。加一层防御式判断就够用了function safeAddModel(viewer, text, format) { const head text.trim().slice(0, 6).toUpperCase(); // PDB 与 mmCIF 的头部特征完全不同先做一次粗筛 if (format pdb !/^(HEADER|ATOM|HETATM|REMARK|CRYST1|MODEL)/.test(head)) { console.warn(文件头不像 PDB实际开头, head); } const model viewer.addModel(text, format); const atoms model.selectedAtoms({}); if (!atoms.length) throw new Error(格式 ${format} 解析出 0 个原子); return model; }slice(0, 6)只取前六个字符做粗筛成本极低但能挡掉大部分「格式名写错」的低级错误。真正要排查时再打印前两百个字符看整体结构。4. 用选择器讲清结构setStyle、表面与交互事件4.1 选择器语法把「全部原子」拆成有语义的分组分子可视化的价值不在于把球画出来而在于「让观众一眼看到重点」。选择器就是这层的抓手它本质是一个属性过滤器对象多属性之间是「与」关系。// 基础样式全部走细线降低视觉噪音 viewer.setStyle({}, { line: { linewidth: 1 } }); // 主链用卡通模型按二级结构上色 viewer.addStyle({ chain: A }, { cartoon: { color: spectrum, style: rectangle, thickness: 0.4 } }); // 特定残基范围用棍状高亮 viewer.addStyle({ chain: A, resi: [45, 46, 47, 48] }, { stick: { radius: 0.25, colorscheme: orangeCarbon } }); // 配体单独上色hetflag 表示非标准残基 viewer.addStyle({ hetflag: true }, { stick: { radius: 0.3, colorscheme: greenCarbon } }); viewer.zoomTo({ hetflag: true }, { duration: 600 }); viewer.render();setStyle是覆盖addStyle是叠加。先用setStyle定一个全局底样式再用addStyle一层层往上加重点这个顺序不能反反过来底样式会把之前的全部冲掉现象是「加了半天高亮一刷新全没了」。resi可以传数组也可以传[10, 50]这样的区间表示从 10 到 50。hetflag: true命中所有非标准氨基酸残基通常是水、离子和配体实际使用中往往要再叠加{resn: HOH, invert: true}把水分子排除掉否则画面里会飘满小红点。colorscheme的可选值里spectrum按残基序号做彩虹渐变chainHetatm按链和配体分色orangeCarbon、greenCarbon这类是按原子类型着色再替换碳的颜色用于区分不同分子。选spectrum是「看整体走向」选碳配色是「区分谁是谁」两个目的不要混用。zoomTo的第二个参数duration是动画时长毫秒传 0 或者不传就是瞬间跳转。做「点击残基列表跳转视角」的交互时给 400 到 800 毫秒过渡观众才能建立空间关联瞬移会让人失去方向感。4.2 表面、标签与悬停拾取分子表面和悬停提示是两个最常被要求、也最容易把性能拖垮的功能。// 给配体周围加半透明范德华表面 viewer.addSurface($3Dmol.SurfaceType.VDW, { opacity: 0.7, color: lightblue }, { hetflag: true }); // 在某个原子位置加文字标签 const target viewer.selectedAtoms({ resn: HEM })[0]; if (target) { viewer.addLabel(活性中心, { position: { x: target.x, y: target.y, z: target.z }, backgroundColor: black, backgroundOpacity: 0.6, fontColor: white, fontSize: 12, showBackground: true }); } // 悬停高亮 回调回调第一个参数是原子对象 viewer.setHoverable({}, true, atom { viewer.addStyle({ serial: atom.serial }, { stick: { radius: 0.4, color: red } }); viewer.render(); }, atom { viewer.removeAllStyles(); // 简化处理真实项目应按 serial 精确还原 viewer.setStyle({}, { stick: { radius: 0.15 } }); viewer.render(); } ); viewer.render();addSurface的第二个参数是表面外观opacity在 0.5 到 0.8 之间比较合适太透明看不出形状太不透明挡住内部结构。第三个参数是选区只给配体加表面是常规做法给整个蛋白加表面在原子数上万时会卡到不可用。addLabel的position必须是三维坐标对象selectedAtoms返回的原子对象里正好带x、y、z直接取用即可。标签是屏幕空间渲染的缩放时文字大小不变这个特性在演示时很好用。setHoverable的最后一个参数是移出回调实际项目里不要用removeAllStyles这种粗暴写法因为那会把主链的 cartoon 一起清掉。正确做法是在进回调前把当前样式快照存下来出回调时还原或者干脆只对「不参与底样式」的原子加高亮。4.3 自转、导出与视图风格演示场景里自转几乎是标配导出图片也是高频需求。viewer.spin(y, 0.8); // 绕 Y 轴自转第二个参数是速度 viewer.setViewStyle({ style: outline, color: black, width: 0.05 }); // 导出 PNG返回 data URI直接塞进 a 标签下载 function exportPng(viewer, filename) { viewer.render(); const uri viewer.pngURI(); const link document.createElement(a); link.href uri; link.download filename || structure.png; link.click(); }spin的第一个参数是旋转轴可以传x、y、z传true会沿用上次的轴第二个参数是速度超过 1.5 会明显晕。停止自转调viewer.spin(false)。setViewStyle的outline给整个视图描一圈黑边用于深色背景下区分边界width的取值范围很小超过 0.1 会糊。pngURI有个必须注意的点如果画布是用preserveDrawingBuffer: false创建的默认值在帧提交之后再去读像素会得到全黑图。所以调用pngURI之前必须先render()一次而且要在同一个事件循环里完成中间不能插入await。5. 避坑与排查五条把视口搞白的记录5.1 现象页面一片空白控制台没有报错原因容器高度为 0或者容器在createViewer调用时还没被插入 DOM。WebGL 画布初始化时会读取容器尺寸读到 0 就创建了一个零尺寸缓冲之后无论怎么渲染都看不见。解决先确认el.clientHeight 0再创建 viewer单页应用里要等组件mounted或useEffect之后调用不要在模块顶层直接执行。用requestAnimationFrame包一层创建逻辑是最省事的兜底。5.2 现象本地双击打开 HTML 是好的部署到服务器后加载失败原因跨域。fetch本地文件走file://协议时行为因浏览器而异但一旦部署到服务结构文件路径相对入口页解析稍有目录层级差异就 404另外如果结构和页面不同源浏览器会直接拦截读取。解决结构文件统一放同源静态目录路径用相对入口页的相对路径服务端对.pdb、.sdf这类扩展名显式配置 MIME 类型为text/plain否则某些服务器会按application/octet-stream返回res.text()拿到的是乱码。上线前用浏览器网络面板确认响应头这一步能省掉大量猜测。5.3 现象切换分子之后画面里出现两层结构或者表面壳浮在空中原因只调了addModel没有清理旧数据。模型、表面、标签是三类独立挂载的对象removeAllModels只清模型。解决封装一个统一的clearScene函数里面依次调removeAllLabels、removeAllSurfaces、removeAllModels再render。所有切换入口都走这个函数不要各处手写漏一个就出一次这种问题。5.4 现象拖窗口大小之后分子被拉扁或者只占了左下角一小块原因只改了 CSS 尺寸没调viewer.resize()画布缓冲仍是旧尺寸浏览器把旧画面拉伸到新容器上。解决监听resize事件并节流回调里先viewer.resize()再viewer.render()如果容器尺寸变化不是由窗口触发的比如侧边栏折叠用ResizeObserver监听容器本身比监听 window 更准。5.5 现象页面停留几分钟后越来越卡切换几次分子后直接假死原因WebGL 资源泄漏。每次新建 viewer 或者频繁增删表面GPU 上的缓冲和纹理不会自动回收尤其是表面网格一个中等大小的蛋白表面能占几十兆显存。解决切换结构时复用同一个 viewer 实例只换模型不换 viewer确实要销毁时调用viewer.clear()并移除容器里的 canvas 节点。做单页应用时在组件卸载钩子里执行这套清理比依赖浏览器回收靠得住。6. 进阶大分子不卡、打包不瘦身的两个具体做法6.1 原子数过万时先降视觉密度再谈优化结构超过两万原子时球棍模型会直接把帧率打到个位数。有效的处理顺序是先换绘制模式再裁剪选区最后才考虑技术手段。手段具体做法适用场景代价换绘制模式全局line替代sticksphere只看整体走向丢失立体感只画主链只对{atom: CA}加 cartoon大蛋白概览看不到侧链隐藏溶剂{resn: HOH, invert: true}几乎所有场景无分段加载按链拆成多个模型按需挂载多链复合物需要管理状态我一般的顺序是先无条件把水分子和氢原子过滤掉这一步往往就能砍掉一半以上的原子数再把默认样式换成line用户点开某个残基时才用addStyle局部升级成球棍。// 一次性过滤去掉水、去掉氢只剩重原子 viewer.setStyle({ resn: HOH, invert: true, elem: H, invert: true }, { line: { linewidth: 1 } });invert: true表示「取反」同一个选择器对象里出现两个invert会互相干扰正确写法是拆成两次调用第一次把所有原子设成透明或极细线第二次对目标选区addStyle覆盖。这个坑我踩过一次画面上什么都不剩查了半小时才反应过来是选择器语义冲突。6.2 打包体积与加载时机完整的分子引擎加上解析器体积不小首屏就同步加载会拖慢交互。走打包器时用动态导入把这块延后let viewerPromise null; async function getViewer(el) { if (!viewerPromise) { viewerPromise import(3dmol).then(mod { // 不同构建产物的导出名不一致装完先 console.log(Object.keys(mod)) const lib mod.default || mod; return lib.createViewer(el, { backgroundColor: white }); }); } return viewerPromise; } // 用户滚动到视口区域再初始化 const io new IntersectionObserver(async entries { if (entries[0].isIntersecting) { io.disconnect(); const viewer await getViewer(document.getElementById(viewport)); // 后续加载逻辑挂在 viewer 上 } }, { threshold: 0.2 }); io.observe(document.getElementById(viewport));import()返回的模块对象结构取决于构建版本直接.createViewer有可能拿到 undefined所以在开发阶段先打一次Object.keys(mod)看清导出结构再写死比在生产环境试错成本低得多。IntersectionObserver的threshold: 0.2表示容器露出两成才触发配合「结构文件同时开始预取」可以让用户几乎感知不到等待。6.3 一个验证渲染是否真的更新的习惯render()是显式提交任何一次改动之后忘了调它画面就不变而控制台不会有任何提示。我现在的习惯是在封装层里做一层代理所有会改动场景的方法addStyle、setStyle、addLabel、zoomTo统一走一个包装函数函数末尾自动补render。从那以后我每次改完样式库都强制走一遍「去掉水 → 换线框 → 缩放 → 再切回球棍」这条回归路径因为绝大多数渲染问题都藏在这四个动作的衔接处而不是首次加载。希望这套拆法能帮到你少走一遍把视口搞白的弯路。本文还有配套的精品资源点击获取