简介这份前端项目资源以3Dmol.js为核心面向具备一定JavaScript基础、希望在网页中实现分子结构可视化的开发者与化学教育工作者。它解决的是在浏览器端解析并渲染PDB、MOL、SDF等分子数据、构建可交互三维模型的问题适合用于化学教学演示、科研数据展示等场景。压缩包为zip格式整体约136.09MB文件总数与类型明细上游暂未提供从描述看应包含库文件、示例页面及配套静态资源。已有341人学习关注。通过该资源读者可掌握WebGL渲染、分子格式解析、3D模型构建、旋转缩放与高亮交互、动画更新、外观定制及响应式适配等关键环节并了解大型分子结构下的性能优化思路为搭建互动性强、视觉效果出色的在线化学可视化应用提供可复用的前端实践参考。1. 分子可视化前端从 3Dmol.zip 看浏览器里的结构渲染第一次在浏览器里打开一个蛋白质结构文件看到三维分子模型能拖拽旋转、缩放、切换显示样式那种感觉和看静态图片完全不同。3Dmol.zip 这个前端项目标题指向的正是这类场景用 3Dmol.js 在网页端渲染分子结构。它解决的核心问题是——不装任何桌面软件打开浏览器就能查看 PDB、SDF、MOL2 等格式的分子文件并且支持球棍模型、卡通模型、表面渲染等多种展示方式。适合谁做计算化学、结构生物学、药物设计方向的前端开发者或者需要把分子数据嵌入 Web 应用的全栈工程师。这个方向值不值得投入如果你的业务涉及分子数据展示、教学演示、在线分析平台那它几乎是目前最轻量的选择。2. 3Dmol.js 的渲染管线与选型逻辑2.1 为什么是 WebGL 而不是 Canvas 2D分子渲染的本质是大量原子和键的实时绘制。一个中等大小的蛋白质动辄几千个原子每个原子要画球体每条键要画圆柱。如果用 Canvas 2D 的 API 逐个绘制帧率会迅速掉到个位数。3Dmol.js 底层走的是 WebGL把原子坐标、颜色、半径打包成顶点缓冲一次性提交给 GPU。这是它能流畅旋转缩放的根本原因。选型时我一般会对比三个方案3Dmol.js、NGL Viewer、Mol*。3Dmol.js 的优势在于 API 极简几行代码就能出图适合快速集成NGL Viewer 功能更重支持轨迹播放和复杂选择语法Mol* 是新一代框架性能最好但学习曲线陡。如果你的需求是「在页面里嵌一个分子查看器支持常见格式和交互」3Dmol.js 的投入产出比最高。2.2 最小可运行示例在页面里加载一个 PDB 文件先看一段能直接跑起来的最小代码。假设你已经通过 npm 安装了 3dmol或者用 script 标签引入了 CDN 版本。!DOCTYPE html html head meta charsetutf-8 title分子查看器/title script srchttps://3dmol.org/build/3Dmol-min.js/script style #viewer { width: 800px; height: 600px; position: relative; } /style /head body div idviewer/div script // 创建查看器实例绑定到容器 let viewer $3Dmol.createViewer(document.getElementById(viewer), { backgroundColor: white // 背景色设为白色 }); // 加载 PDB 文件这里用远程 URL 示例 // 实际项目中可以替换为本地文件或后端接口返回的文本 $3Dmol.download(pdb:1crn, viewer, {}, function() { // 下载完成后设置显示样式 viewer.setStyle({}, { cartoon: { color: spectrum } // 卡通模型按光谱着色 }); viewer.zoomTo(); // 自动缩放至合适视野 viewer.render(); // 触发渲染 }); /script /body /html这段代码的逻辑很直白创建 viewer 实例下载 PDB 结构设置样式渲染。$3Dmol.download的第一个参数是标识符pdb:1crn表示从 RCSB 数据库拉取。第二个参数是 viewer 对象。第三个参数是选项对象可以传{ multimodel: true }之类。回调函数在下载完成后执行此时结构数据已经注入 viewer。参数说明setStyle的第一个参数是选择器空对象{}表示所有原子。第二个参数是样式对象cartoon表示卡通模型color: spectrum表示按残基序号从蓝到红渐变。如果你只想显示配体可以传{ hetflag: true }作为选择器。2.3 样式系统与选择器语法3Dmol.js 的样式系统是它的核心抽象。每个原子可以同时应用多种样式比如同时显示球体和标签。常见样式包括样式名效果适用场景sphere球体小分子、离子stick棍状键配体、小分子cartoon卡通带状蛋白质主链surface分子表面结合口袋分析line线框大体系快速预览label文字标签标注关键残基选择器语法借鉴了 JQuery 的思路。{ resn: HEM }选中所有血红素残基{ chain: A }选中 A 链{ elem: C }选中碳原子。多个条件可以组合比如{ chain: A, resi: 42 }选中 A 链 42 号残基。这个语法在文档里有完整说明但实际用的时候容易踩坑——比如resi是数字resn是字符串写反了不会报错但选不中。2.4 从静态展示到交互分析基础渲染跑通后下一步是加交互。3Dmol.js 支持点击、悬停事件可以获取被点击原子的信息。// 绑定点击事件 viewer.setClickable({}, true, function(atom, viewer) { // atom 对象包含点击到的原子信息 if (atom) { // 在控制台输出原子详情 console.log(元素:, atom.elem); console.log(残基:, atom.resn, atom.resi); console.log(坐标:, atom.x, atom.y, atom.z); // 在页面上显示一个标签 viewer.addLabel( atom.resn atom.resi, { position: { x: atom.x, y: atom.y, z: atom.z }, backgroundColor: yellow, fontColor: black, fontSize: 12 } ); viewer.render(); } });setClickable的第一个参数是选择器第二个是是否可点击第三个是回调。回调里的atom对象包含elem、resn、resi、x、y、z等字段。addLabel在指定坐标添加文字标签样式对象控制背景色、字体颜色和大小。注意每次点击都会新增标签如果不想累积需要先调用viewer.removeAllLabels()。这个交互模式在药物设计场景里很实用用户点击结合口袋里的残基页面侧边栏显示该残基的详细信息或者高亮与之相互作用的配体原子。3. 把 3Dmol.zip 跑起来本地集成与数据对接3.1 项目结构拆解与依赖安装拿到一个前端项目压缩包第一步不是急着打开 index.html而是先看目录结构和依赖声明。典型的 3Dmol 前端项目结构大致如下3Dmol-project/ ├── index.html ├── package.json ├── src/ │ ├── main.js │ ├── viewer.js │ └── styles.css ├── public/ │ └── data/ │ └── sample.pdb └── dist/ └── bundle.js如果 package.json 里声明了 3dmol 依赖直接npm install然后npm run dev。如果没有需要手动加。我一般会先确认版本3Dmol.js 的 API 在不同大版本间有细微差异比如$3Dmol.createViewer的参数在 1.x 和 2.x 里基本一致但某些样式属性名有调整。# 初始化项目如果还没有 package.json npm init -y # 安装 3Dmol.js npm install 3dmol # 如果项目用 webpack 或 vite确认构建配置里没有把 3dmol 排除 # 安装开发服务器 npm install -D vite安装完成后在入口文件里引入import * as $3Dmol from 3dmol; // 或者按需引入 import { createViewer, download } from 3dmol;注意3Dmol.js 在 npm 上的包名是3dmol但全局变量是$3Dmol。用 ES module 引入时需要确认构建工具能正确处理它的 UMD 包装。Vite 一般没问题Webpack 4 可能需要加resolve.alias。3.2 加载本地 PDB 文件的三种方式远程下载适合演示但实际项目里分子数据往往来自后端接口或用户上传。三种常见方式方式一后端返回文本前端直接解析。// 假设后端接口返回 PDB 格式的纯文本 fetch(/api/structure/1crn) .then(res res.text()) .then(pdbText { // 直接用 addModel 添加文本数据 viewer.addModel(pdbText, pdb); viewer.setStyle({}, { cartoon: { color: spectrum } }); viewer.zoomTo(); viewer.render(); });addModel的第二个参数是格式标识支持pdb、sdf、mol2、xyz等。如果格式写错解析会失败但控制台不一定报错表现为模型空白。方式二用户上传文件FileReader 读取。document.getElementById(file-input).addEventListener(change, function(e) { const file e.target.files[0]; if (!file) return; const reader new FileReader(); reader.onload function(evt) { const content evt.target.result; // 根据文件扩展名判断格式 const ext file.name.split(.).pop().toLowerCase(); const format ext pdb ? pdb : ext sdf ? sdf : mol2; viewer.addModel(content, format); viewer.setStyle({}, { stick: {} }); viewer.zoomTo(); viewer.render(); }; reader.readAsText(file); });方式三静态文件放在 public 目录用相对路径请求。// 文件放在 public/data/sample.pdb fetch(/data/sample.pdb) .then(res res.text()) .then(data { viewer.addModel(data, pdb); viewer.setStyle({}, { cartoon: {} }); viewer.render(); });三种方式各有适用场景。后端接口适合动态数据用户上传适合交互式工具静态文件适合演示页面。我一般会在项目里同时保留后两种方便调试。3.3 多模型与轨迹播放的处理有些 PDB 文件包含多个模型比如 NMR 结构或者你需要在不同构象之间切换。3Dmol.js 支持多模型加载和动画播放。// 加载多模型 PDB viewer.addModelsAsFrames(pdbText, pdb); // 设置样式 viewer.setStyle({}, { cartoon: { color: spectrum } }); // 播放动画间隔 200 毫秒 viewer.animate({ loop: forward, interval: 200 }); // 或者手动切换到第 5 帧 viewer.setFrame(5); viewer.render();addModelsAsFrames会把每个 MODEL 记录当作一帧。animate的loop参数可以是forward、backward、pingpong。interval单位是毫秒。如果帧数很多建议先viewer.setStyle再播放避免每帧重绘样式导致卡顿。3.4 表面渲染与口袋分析分子表面在药物设计里很关键。3Dmol.js 支持范德华表面和溶剂可及表面。// 添加范德华表面 viewer.addSurface($3Dmol.SurfaceType.VDW, { opacity: 0.7, color: white }, { chain: A }); // 只对 A 链生成表面 // 添加溶剂可及表面 viewer.addSurface($3Dmol.SurfaceType.SAS, { opacity: 0.5, color: lightblue }, { resn: HEM }); // 只对血红素周围生成 viewer.render();addSurface的第一个参数是表面类型VDW是范德华表面SAS是溶剂可及表面SES是溶剂排除表面。第二个参数是样式opacity控制透明度color控制颜色。第三个参数是选择器限定生成表面的区域。表面计算比较耗时大体系建议先用选择器缩小范围。4. 避坑与排查分子渲染里那些让人翻车的细节4.1 模型加载成功但页面空白现象控制台没有报错addModel也执行了但 viewer 区域一片白。原因通常有三种一是容器没有设置宽高viewer 默认尺寸为 0二是render()没有调用三是背景色和模型颜色撞了比如白色背景加白色球体。解决先检查容器 CSS确保width和height都有明确值。然后在addModel之后加viewer.zoomTo()和viewer.render()。如果还不行把背景色改成黑色试试排除颜色问题。4.2 选择器写对了但选不中原子现象setStyle({ resn: HEM }, ...)没有任何效果。原因字段名拼写错误或者数据类型不匹配。resi是数字resn是字符串chain是字符串elem是字符串。另外有些 PDB 文件的残基名带空格比如HEM 需要 trim。解决先用viewer.getAtoms()打印所有原子信息确认字段名和值。或者用viewer.setStyle({}, { stick: {} })先给所有原子加样式确认渲染管线没问题再逐步缩小选择器范围。4.3 大分子体系卡顿严重现象加载一个几万原子的结构后旋转缩放掉帧明显。原因默认样式对每个原子都画球体和键顶点数爆炸。表面渲染更是计算密集型。解决大体系先用line或cartoon样式不要用sphere。表面渲染只对结合口袋区域生成不要全蛋白生成。如果还卡考虑用 NGL Viewer 或 Mol* 替代它们在处理大体系时做了更多优化。4.4 本地文件路径在构建后失效现象开发环境正常npm run build后部署到服务器分子文件 404。原因构建工具把静态资源打包到了dist/assets目录路径变了。或者用了绝对路径/data/sample.pdb但部署到了子目录。解决把分子文件放在public目录用相对路径引用。Vite 里public目录的文件会原样复制到dist根目录。Webpack 里需要配置copy-webpack-plugin。如果部署在子目录用import.meta.env.BASE_URL拼接路径。4.5 移动端触摸事件冲突现象在手机上单指旋转正常但双指缩放会触发页面滚动。原因viewer 的触摸事件没有阻止默认行为。解决在容器上添加 CSStouch-action: none;或者在 viewer 初始化后手动绑定事件阻止默认行为。3Dmol.js 较新版本已经处理了这个问题但如果用的旧版本需要自己加。#viewer { touch-action: none; }5. 进阶技巧用 3Dmol.js 做差异对比与批量截图5.1 双视图同步对比两个构象药物设计里经常需要对比两个构象的差异比如 apo 和 holo 状态。3Dmol.js 支持创建两个 viewer然后同步它们的旋转矩阵。// 创建两个 viewer const viewer1 $3Dmol.createViewer(document.getElementById(viewer1), { backgroundColor: white }); const viewer2 $3Dmol.createViewer(document.getElementById(viewer2), { backgroundColor: white }); // 加载两个结构 viewer1.addModel(pdbText1, pdb); viewer2.addModel(pdbText2, pdb); // 设置相同样式 [viewer1, viewer2].forEach(v { v.setStyle({}, { cartoon: { color: spectrum } }); v.zoomTo(); v.render(); }); // 同步旋转监听 viewer1 的视角变化应用到 viewer2 viewer1.setViewChangeCallback(function() { const view viewer1.getView(); viewer2.setView(view); viewer2.render(); });setViewChangeCallback在用户旋转 viewer1 时触发getView()返回当前视角矩阵setView()应用到另一个 viewer。这样两个视图始终保持同步。注意setView不会自动触发渲染需要手动调render()。5.2 批量导出高清截图做报告或论文时需要把多个结构批量导出为图片。3Dmol.js 的pngURI()方法可以获取当前画布的 base64 数据。// 导出当前视图为 PNG const pngData viewer.pngURI(); // pngData 是 data:image/png;base64,... 格式 // 批量处理多个结构 const structures [1crn, 1ubq, 2ptc]; const results []; structures.forEach(pdbId { $3Dmol.download(pdb:${pdbId}, viewer, {}, function() { viewer.setStyle({}, { cartoon: { color: spectrum } }); viewer.zoomTo(); viewer.render(); // 等待渲染完成后导出 setTimeout(() { results.push({ id: pdbId, image: viewer.pngURI() }); // 清空当前模型准备下一个 viewer.removeAllModels(); }, 500); }); });pngURI()返回的是 data URI可以直接赋给img的src或者传给后端保存为文件。注意导出前要确保渲染完成setTimeout是一种简单粗暴的等待方式更可靠的做法是监听渲染事件。另外removeAllModels()会清空所有模型但不会重置视角下一个结构加载后需要重新zoomTo()。5.3 自定义颜色映射与残基高亮默认的光谱着色是按残基序号渐变但有时候需要按 B-factor、按链、按自定义属性着色。// 按 B-factor 着色 viewer.setStyle({}, { cartoon: { colorfunc: function(atom) { // B-factor 越高越红越低越蓝 const b atom.b || 0; const maxB 100; // 假设最大 B-factor 为 100 const ratio Math.min(b / maxB, 1); // 从蓝色 (0,0,255) 到红色 (255,0,0) 插值 const r Math.round(255 * ratio); const bVal Math.round(255 * (1 - ratio)); return rgb(${r},0,${bVal}); } } }); // 高亮特定残基 viewer.addStyle({ resi: 42 }, { stick: { color: red, radius: 0.3 } }); viewer.render();colorfunc接收 atom 对象返回 CSS 颜色字符串。addStyle在已有样式上叠加不会覆盖。这个技巧在展示突变位点或结合位点时很实用。5.4 一个我常犯的错误早期做项目时我总喜欢在addModel之后立刻调setStyle和render结果偶尔遇到模型没加载完就渲染页面空白。后来养成习惯所有渲染操作都放在download的回调里或者用addModel的返回值确认模型已添加。另外zoomTo()一定要在setStyle之后调否则视角可能不对。这些细节看起来小但调试起来很费时间。希望帮到你。本文还有配套的精品资源点击获取