简介：这份前端项目资料围绕 3Dmol.js 的 Web 分子可视化展开，面向前端开发者、化学教学与科研展示场景，帮助在浏览器中呈现可交互的三维分子结构。内容涉及 WebGL 渲染、JavaScript API、PDB/MOL/SDF 等分子格式解析、原子与化学键建模、旋转缩放高亮等交互，以及动画更新、外观定制、Web 应用集成、性能优化和响应式适配等知识点，适合具备一定前端基础、希望补齐科学可视化能力的学习者。压缩包约 136.09MB，文件清单与类型明细上游暂未提供，解压前需预留足够空间。页面显示已有 342 人学习或下载，可作为同类 3D 分子展示项目的参考入口。通过其中的项目材料，读者可理解从结构数据到三维场景的落地路径，梳理交互接口与渲染配置，并为化学教学、结构浏览或科研演示类前端应用积累可复用的实现思路。

1. 一个分子结构查看器，凭什么不该做成桌面软件

某高校的结构生物学课程留了份作业：把一段蛋白质结构数据在浏览器里打开，转着看，标出活性口袋附近的几个残基，再截图贴进报告。学生的第一反应是装个桌面软件，第二反应是装不上——机房机器没有管理员权限，笔记本又是五花八门的系统。需求最后落到一个纯前端项目上：用 3Dmol 做内核的分子结构在线可视化查看器，也就是这份前端项目-3Dmol.zip。它不连后端、不装环境，静态托管就能跑，打开一个结构文件就能立刻出三维模型，还能切样式、做测量、导图片。这套东西适合三类人：做毕设想要一个「有画面、能演示、逻辑还完整」题目的学生；带课设需要一套现成骨架改吧改吧就能交的老师；以及要给内部文档或教学页面嵌一个轻量分子查看器的开发者。下面按真实交付顺序把方案拆开讲。

2. 技术选型与总体架构：三层结构与四个模块的职责划分

2.1 渲染内核为什么选 3Dmol.js，而不是自己搭 WebGL 管线

很多人第一反应是「Three.js 不是能画球吗，我自己拼一个」。真动手就会撞上三堵墙。第一堵是图元数量：一个中等大小的蛋白动辄三四千个原子，球棍模型意味着几千个球体加几千根圆柱，不合并几何、不做实例化，draw call 直接把帧率拖到个位数。第二堵是分子语义：卡通模型里那根螺旋带不是圆柱，是沿主链 Cα 原子做样条插值后扫掠出来的曲面，还得处理 β 折叠的箭头方向。第三堵是表面计算：溶剂可及表面要先算每个原子的范德华球并求并集，再重构成三角网格，本质是计算几何问题，不是渲染问题。

自己从零搭这三块，一个学期基本就没了，而且做完也只是个半成品查看器。3Dmol.js 把这些都封装好了：它内置 PDB、SDF、MOL2、XYZ、CIF、MMCIF 等格式的解析器，内置 cartoon / stick / sphere / line / cross / surface 六类样式，卡通模型的样条细分、表面网格的生成都是现成的，对外只暴露一层很薄的语义 API。代价是它不如通用引擎灵活，想做粒子特效、后处理泛光这类效果会别扭——但分子查看器根本不需要这些。

选型结论很干脆：这个项目的价值不在渲染内核，而在把内核包装成一个可用的产品——加载入口、样式面板、测量工具、异常兜底、验收清单。内核交给成熟库，剩下的活才是这份方案真正要交付的东西。

提示：不要在项目里同时引入两个分子渲染库「以防万一」。两套渲染器抢同一个 canvas，尺寸和相机状态会互相打架，排查起来极其痛苦。

2.2 三层结构：数据层、渲染层、交互层各管什么

整个前端拆成三层，边界划清楚，后面加功能才不会互相污染。数据层只负责「把字节变成模型」：文件读取、格式判别、解析调用、模型缓存、错误上报，它不认识 DOM，也不认识相机。渲染层只负责「把模型变成画面」：持有 viewer 实例、维护当前样式策略、管相机与背景、处理尺寸变化。交互层只负责「把人的动作变成指令」：工具栏状态、鼠标拾取、测量流程、标签增删、导出动作。

三层之间的通信走一个很小的中央状态对象，而不是互相直接调用。比如用户在样式面板点了「卡通」，交互层只改state.style = 'cartoon'，然后发一个style:change事件；渲染层监听这个事件，自己算出对应的setStyle配置再执行。这样做的直接好处是：样式面板和渲染逻辑可以分别测试，改面板布局不会碰坏渲染，改渲染参数也不用动 UI。

还有一个容易被忽略的角色：状态与事件总线。它不属于任何一层，但三层都要用它。我的做法是一个三十行左右的极简实现，on/off/emit三个方法足够，不引第三方状态库——这个体量的项目引 MobX 或 Pinia 属于杀鸡用牛刀，反而让答辩时讲不清楚数据流。

2.3 目录结构与依赖清单

目录按层切，不按文件类型切。按components/、utils/这种切法，做一个功能要在四五个目录之间跳，改着改着就乱了。按层切的好处是「这个文件该放哪」永远有唯一答案。

src/ ├── data/ # 数据层 │ ├── loader.js # 三条加载通路的统一入口 │ ├── format.js # 扩展名 / 内容特征 -> 格式标识 │ └── cache.js # 已解析模型的内存缓存 ├── render/ # 渲染层 │ ├── viewer.js # viewer 实例的创建与销毁 │ ├── styles.js # 样式名 -> 3Dmol 配置对象的映射表 │ └── camera.js # 聚焦、复位、自转 ├── interact/ # 交互层 │ ├── toolbar.js # 工具栏状态机 │ ├── measure.js # 距离 / 角度测量 │ └── label.js # 残基标签 ├── core/ │ ├── bus.js # 事件总线 │ └── state.js # 中央状态 └── main.js # 组装，只做装配不做逻辑

依赖清单刻意保持克制，package.json里运行时依赖只有两项：3Dmol 本体，以及一个构建工具。不引 UI 框架是权衡后的决定——这个项目的界面元素总共不到三十个，手写 DOM 操作配合事件委托完全够用，引框架反而让包体积翻几倍，还得解释一堆和分子可视化无关的配置。

{ "name": "mol-viewer", "type": "module", "dependencies": { "3dmol": "^2.4.0" }, "devDependencies": { "vite": "^5.0.0" }, "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" } }

type: "module"意味着源码直接走 ES Module，浏览器原生支持，调试时不用管打包产物。vite build出来的产物是纯静态文件，扔到任意静态托管上就能跑，这也是这套方案能「双击 index.html 就能演示」的底气。构建时记得把 3Dmol 的 worker 资源和内置的字体、颜色表一起带上，否则线上会出现本地正常、部署后样式全丢的经典翻车。

3. 数据接入与结构解析：从一段 PDB 文本到可渲染模型

3.1 三条加载通路：本地文件、远程地址、粘贴文本

用户拿到结构数据的方式不止一种。有人手里是下载好的.pdb文件，有人只有一个网址，还有人在报告里复制了一段几十行的文本想快速看一眼。三条通路如果各写一套，后面加校验、加提示、加缓存就要改三遍，所以统一收敛到一个入口函数。

// src/data/loader.js import { detectFormat } from './format.js' /** * 统一加载入口 * @param {Object} source * @param {'file'|'url'|'text'} source.kind 来源类型 * @param {File} [source.file] 本地文件，kind=file 时必填 * @param {string} [source.url] 远程地址，kind=url 时必填 * @param {string} [source.text] 粘贴文本，kind=text 时必填 * @param {Object} viewer 渲染层的 viewer 实例 * @returns {Promise<{model: Object, format: string, atomCount: number}>} */ export async function loadStructure(source, viewer) { let raw = '' let hint = '' if (source.kind === 'file') { // 超过 20MB 的结构直接拒绝，避免主线程长时间阻塞 if (source.file.size > 20 * 1024 * 1024) { throw new Error('FILE_TOO_LARGE') } raw = await source.file.text() hint = source.file.name.split('.').pop() } else if (source.kind === 'url') { const res = await fetch(source.url) if (!res.ok) throw new Error('NETWORK_' + res.status) raw = await res.text() hint = source.url.split('.').pop() } else { raw = source.text } if (!raw.trim()) throw new Error('EMPTY_CONTENT') // 先按扩展名猜，猜不出来再看内容特征 const format = detectFormat(hint, raw) // multimodel: false 只取第一个模型，NMR 结构动辄几十个模型 const model = viewer.addModel(raw, format, { multimodel: false, keepHets: true }) const atomCount = model.selectedAtoms({}).length if (atomCount === 0) { viewer.removeAllModels() throw new Error('NO_ATOM_PARSED') } return { model, format, atomCount } }

几个参数值得单独说。multimodel: false是关键的一行：核磁共振解析出来的结构文件常常包含二十个以上的构象模型，全塞进去会让渲染量翻二十倍，而教学演示只需要看第一个。keepHets: true决定是否保留非标准残基——水分子、配体、金属离子都算，含配体的复合物如果不保留，活性口袋那块就是空的，正好把最该看的东西丢了。atomCount不只是统计数字，它是后面所有校验和验收的基准线。

detectFormat的判断顺序是「扩展名优先，内容兜底」。扩展名.pdb、.ent归为pdb，.sdf、.mol归为sdf，.cif、.mmcif归为cif，.mol2归为mol2；没有扩展名的场景（粘贴文本、无后缀下载链接）就去数特征行——以ATOM或HETATM开头的行多就是 PDB，以data_开头就是 CIF，含@<TRIPOS>就是 MOL2。这一步做扎实，后面用户乱传文件时的错误提示才有意义。

3.2 解析失败与脏数据的兜底

结构文件是出了名的不规矩。同是 PDB，有的列宽严格对齐，有的被各种脚本改过；有些文件头部声明了一堆REMARK，正文却是空的；还有些文件原子坐标是NaN，解析器直接吐出一个原子为空的模型却不报错。如果不在入口处拦一道，用户看到的就是「点了加载，什么都没发生」，这种体验比报错还糟。

兜底分三层。第一层是入口校验：空内容、超大文件、扩展名和内容对不上，全在这里拦掉，抛出带错误码的异常。第二层是解析后校验：atomCount === 0说明解析器没吃到东西，立刻回滚 model 并提示「文件可能不是标准结构格式，请确认是否为 PDB / CIF / SDF」。第三层是渲染后校验：调用viewer.zoomTo()之后判断相机是否真的收敛，如果所有原子坐标都是同一个点，包围盒是零，缩放会失效，这时候给一个「结构坐标异常」的提示比留一片空白强。

错误码到用户提示的映射建议放一张表，别在代码里散着写if...else拼字符串。这样后面加语言包、加日志上报都只改一处。

回滚这一步很关键。3Dmol 的addModel一旦成功调用，模型就挂到 viewer 上了，后续校验失败必须显式removeAllModels()，否则残留一个空模型会让下一次加载的zoomTo()计算出错误的包围盒，表现是「第二次打开文件时视角飘到天上去」。

3.3 大结构的加载体验：先给轮廓，再给细节

单链蛋白一般两三千个原子，渲染毫无压力；但复合物、病毒衣壳、核糖体这类结构动辄几万到几十万原子，一次setStyle带 cartoon 会让主线程卡住两三秒，页面像死了一样。这不是渲染库的问题，是几何生成本身的成本。

通常的做法是分级加载：拿到模型后立刻用line样式铺一遍，线条渲染的几何量最小，几万原子也是瞬间出图，用户马上能看到东西；紧接着在下一帧（requestAnimationFrame）里把样式切成最终要的 cartoon 或 sphere。中间那一两百毫秒的过渡，视觉上就是「先出现骨架，再填充细节」，比转圈等待体面得多。

// 大结构的渐进式渲染 export function renderProgressively(viewer, model, finalStyle) { const atoms = model.selectedAtoms({}).length if (atoms < 5000) { // 小结构没必要分两步，直接上最终样式 viewer.setStyle({}, finalStyle) viewer.zoomTo() viewer.render() return } // 第一步：线条铺底，几十毫秒内出图 viewer.setStyle({}, { line: { linewidth: 1 } }) viewer.zoomTo() viewer.render() // 第二步：下一帧再做重活，避免阻塞首屏 requestAnimationFrame(() => { viewer.setStyle({}, finalStyle) viewer.render() }) }

阈值 5000 是实测调出来的经验值，不是拍脑袋：低于这个数量，两步走反而多一次渲染，得不偿失；高于这个数量，一步走的卡顿开始被用户感知。这个数字可以根据目标机器改，低配环境调到 3000 更稳。另外requestAnimationFrame只保证「下一帧之前不执行」，不保证计算不阻塞主线程——真要处理几十万原子的超大结构，还是得给用户一个明确的「结构较大，渲染约需数秒」的提示，让人知道页面没死。

4. 视图与交互实现：六种渲染样式和四个操作

4.1 样式策略：把专业参数翻译成人能点懂的按钮

3Dmol 的setStyle接受的是一个嵌套配置对象，参数名对非专业用户极不友好。cartoon: { color: 'spectrum', style: 'oval' }里style还能取trace、tube、rectangle，color可以是一个颜色值，也可以是spectrum这种按链着色的方案，还支持自定义函数。把这些原样摊给用户，等于没做产品。

我的做法是在渲染层维护一张样式映射表，交互层只认表里的键：cartoon（卡通）、stick（球棍）、sphere（空间填充）、line（骨架线）、surface（表面）、trace（主链轨迹）。每个键对应一套预设参数，用户点按钮，代码查表，不接触底层配置。

// src/render/styles.js export const STYLE_PRESETS = { cartoon: { cartoon: { color: 'spectrum', style: 'oval', thickness: 0.4 } }, stick: { stick: { radius: 0.15, colorscheme: 'Jmol' } }, sphere: { sphere: { scale: 1.0, colorscheme: 'Jmol' } }, line: { line: { linewidth: 1.2, colorscheme: 'Jmol' } }, trace: { cartoon: { style: 'trace', color: 'spectrum', thickness: 0.5 } }, surface: { cartoon: { color: 'spectrum', opacity: 0.6 } } // surface 另走 addSurface } /** * 应用样式预设 * @param {Object} viewer * @param {string} presetKey 上面表里的键 * @param {Object} [options] * @param {boolean} [options.append] true 表示叠加而不是替换 */ export function applyPreset(viewer, presetKey, options = {}) { const preset = STYLE_PRESETS[presetKey] if (!preset) return // 先清空，再设置。3Dmol 的 setStyle 是叠加语义，不清会残留 viewer.setStyle({}, {}) viewer.setStyle({}, preset) if (presetKey === 'surface') { viewer.removeAllSurfaces() // VDW 表面：按范德华半径生成，opacity 控制透明度 viewer.addSurface('VDW', { opacity: 0.75, color: 'white' }, {}) } else { viewer.removeAllSurfaces() } viewer.render() }

setStyle({}, {})这一行值得单独强调。3Dmol 的setStyle语义是「对匹配的原子应用这些样式」，传入空对象{}表示清除选择范围内的样式，传入{}作为选择器表示「所有原子」。不知道这个语义的人会写出一堆「切到球棍之后卡通模型还在」的 bug，这是这份方案里最高频的翻车点，后面还会展开。

参数上还有两个可调项。cartoon.thickness控制螺旋带的粗细，取值 0.2 到 0.8 之间视觉上都合理，课件演示建议 0.4。sphere.scale是范德华半径的缩放系数，1.0 是真实比例，0.8 能让原子球之间留出缝隙，看清内部结构，教学场景比 1.0 更实用。表面透明度的上限建议 0.85，再高就看不清内部的卡通模型了。

4.2 选中、高亮与标签：基于选择器表达式的过滤

分子可视化最核心的交互动作其实只有一个：「我要看这几个残基」。用户心里想的是「A 链上第 45 号残基」，代码里要表达成{ chain: 'A', resi: 45 }。3Dmol 的选择器支持链、残基号、残基名、原子名、元素、模型序号这些维度组合，还有within这种空间范围选择——「距离配体 5 埃以内的所有残基」可以写成{ within: { distance: 5, sel: { resn: 'LIG' } } }，这个能力在讲活性口袋时价值极高。

高亮的实现是「在已有样式上叠加一层」，而不是替换。叠加用viewer.addStyle或再调一次setStyle带选择器，区别在于前者不清空既有样式。

// 高亮指定残基：保留全局卡通样式，只在选中残基上叠加球棍 export function highlightResidues(viewer, selector, color = '#ff5c5c') { viewer.addStyle(selector, { stick: { radius: 0.25, color } }) viewer.addLabel( buildLabelText(selector), { position: centerOf(viewer, selector), // 选中原子的质心 backgroundColor: '#1e293b', backgroundOpacity: 0.85, fontColor: 'white', fontSize: 12, borderThickness: 0 } ) viewer.render() } // 消除高亮：只清选中范围的样式，不动全局 export function clearHighlight(viewer, selector) { viewer.setStyle(selector, {}) viewer.removeAllLabels() viewer.render() }

centerOf需要自己写，思路是viewer.selectedAtoms(selector)拿到原子数组，累加x、y、z除以数量。空数组要做保护，否则就是NaN坐标，标签飞到画面外面去，用户以为程序崩了。

removeAllLabels是另一个隐雷：它会删掉所有标签，包括用户自己手动加的那些。如果项目里同时存在「自动高亮带出的标签」和「手动标注的标签」，就得给标签打上来源标记，清除时按来源删。3Dmol 的标签对象没有自定义属性槽，通常的做法是在应用层维护一个labels: [{ id, selector, text }]的数组，需要重建时先removeAllLabels()再按数组逐条addLabel。多花二十行代码，换掉一整类「标签莫名消失」的问题。

4.3 测量与截图：把「看图」变成「能交作业」

只是旋转缩放，学生交上去的报告还是空的。真正让这个项目从玩具变成工具的是两个功能：几何测量和图片导出。

测量的核心是点选原子。3Dmol 提供setClickable给某个选择范围挂回调，回调里能拿到被点中的原子对象，含元素、残基、坐标。距离就是两点欧氏距离，角度就是三点的向量夹角，公式初中就够用，没必要引数学库。

// src/interact/measure.js const picked = [] // 存放已点选的原子坐标 /** * 注册测量模式 * @param {Object} viewer * @param {'distance'|'angle'} mode * @param {(result: {value: number, unit: string}) => void} onDone */ export function enableMeasure(viewer, mode, onDone) { const need = mode === 'distance' ? 2 : 3 picked.length = 0 viewer.setClickable({}, true, (atom) => { picked.push({ x: atom.x, y: atom.y, z: atom.z }) if (picked.length < need) return const value = mode === 'distance' ? distance(picked[0], picked[1]) : angle(picked[0], picked[1], picked[2]) onDone({ value, unit: mode === 'distance' ? 'Å' : '°' }) picked.length = 0 // 一轮结束，从头再来 }) } const distance = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z) function angle(a, b, c) { // 以 b 为顶点，计算 ba 与 bc 的夹角 const v1 = { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z } const v2 = { x: c.x - b.x, y: c.y - b.y, z: c.z - b.z } const dot = v1.x * v2.x + v1.y * v2.y + v1.z * v2.z const m1 = Math.hypot(v1.x, v1.y, v1.z) const m2 = Math.hypot(v2.x, v2.y, v2.z) if (m1 === 0 || m2 === 0) return 0 // 夹紧到 [-1,1]，浮点误差会让 acos 得到 NaN const cos = Math.min(1, Math.max(-1, dot / (m1 * m2))) return (Math.acos(cos) * 180) / Math.PI }

距离单位是埃（Å），这是结构生物学的默认单位，1 Å 等于 0.1 纳米。不要自作主张换算成纳米，课件和文献里全是埃，用户看到 3.5 纳米会懵。角度用度不用弧度，同理。Math.min(1, Math.max(-1, ...))这行夹紧看着多余，实际是保命的：两个向量几乎平行时，dot / (m1 * m2)会因为浮点误差算出 1.0000000002，Math.acos直接返回NaN，界面上就是「角度: NaN°」，答辩现场解释不清。

截图用viewer.pngURI()拿 data URI，赋给一个<a download>触发下载。这里有个高频坑：WebGL 的 canvas 默认preserveDrawingBuffer: false，渲染完缓冲区就被清掉，toDataURL可能拿到一张全黑图。解决办法是在创建 viewer 时把preserveDrawingBuffer打开，或者在导出前强制同步调用一次viewer.render()并在同一帧内取图。前者更稳，代价是极轻微的性能损失，对这种应用完全无感。

导出分辨率也得管。默认 canvas 尺寸就是元素尺寸，贴进 Word 放大到 A4 宽会糊。稳妥做法是导出前临时把容器放大到两倍，导出后还原——或者干脆导出 SVG，viewer.svgURI()出来的是矢量图，怎么放都不糊，缺点是超大结构的 SVG 文件会很大，超过十万原子的场景不建议。

5. 避坑与排查：五个最容易翻车的点

5.1 白屏但控制台干净——容器尺寸为 0

现象：页面加载完，viewer 区域一片空白，控制台没有任何报错，zoomTo()、render()调用也不报错。

原因：WebGL 渲染器的画布尺寸在初始化时由容器元素的实际像素尺寸决定。如果容器是display: none状态、或者被 flex 布局压成了 0 高度、或者在visibility: hidden的标签页里初始化，拿到的宽高就是 0，画布尺寸 0×0，渲染执行了但什么都看不见。这类问题最迷惑人的地方在于它不报错。

解决：初始化前断言尺寸，小于阈值就延迟。生产环境的做法是挂一个ResizeObserver，尺寸从 0 变成非 0 时再创建 viewer，同时每次尺寸变化调用viewer.resize()。

const host = document.querySelector('#viewport') const ro = new ResizeObserver(([entry]) => { const { width, height } = entry.contentRect if (width < 10 || height < 10) return // 尺寸没起来，先不初始化 if (!viewer) { viewer = createViewer(host) // 首次有效尺寸才建实例 } else { viewer.resize() // 后续变化只做重排 viewer.render() } }) ro.observe(host)

多标签页的场景还要额外处理：从隐藏标签切回来时，ResizeObserver不一定触发（尺寸没变），但画布内容可能已失效，需要监听visibilitychange手动补一次render()。

5.2 切换样式后旧样式残留——setStyle是叠加语义

现象：点了「球棍」，卡通模型还在；再点「空间填充」，球棍和卡通一起叠着显示，画面越来越乱。

原因：3Dmol 的setStyle(sel, style)语义是「给 sel 匹配的原子应用style」，不是「替换成 style」。连续调用不传空对象清除，样式就会一层层累加。

解决：切样式前先调viewer.setStyle({}, {})清空全局样式，再应用新预设。这个清除动作要封装在applyPreset里，不要让 UI 层去记这个规则——UI 层记不住，今天记住了明天加个新按钮又忘了。

与这个坑同源的是「高亮后想恢复原样」。正确做法是setStyle(selector, {})只清选择范围，千万别图省事写setStyle({}, {})，那会把全局样式一起清掉，用户会看到整个模型突然变成默认线框。

5.3 点表面就卡死——表面计算在主线程

现象：加载了表面样式之后，页面卡住三四秒甚至更久，鼠标转圈，浏览器弹「页面无响应」。

原因：溶剂可及表面的生成需要遍历所有原子、构建空间划分、求范德华球并集、重构成三角网格，复杂度随原子数超线性增长。这个过程默认跑在主线程，几万原子的结构直接把 UI 线程占满。

解决：三条路，按投入排序。最省事的是加阈值——原子数超过两万时禁用表面按钮，并给出提示「当前结构过大，表面渲染已禁用」；进阶一点是降精度，表面计算时可以指定分辨率参数，粗网格能快好几倍，视觉上只是稍微粗糙；彻底解决是把表面计算挪进 Web Worker，但 3Dmol 的表面生成和渲染上下文耦合较紧，改造量不小，课设阶段不建议碰。

5.4 手机上拖不动，或者拖动时页面跟着滚

现象：桌面端一切正常，手机上手指拖动模型，结果是整个页面在上下滚动，模型纹丝不动。

原因：触摸设备上，浏览器默认把单指拖动解释为页面滚动，只有touch-action明确声明为none的元素才会把触摸事件交给 JS。另外，手指是小面积接触，命中测试的容差比鼠标小得多，点不中原子是常态。

解决：给画布容器加touch-action: none;和overscroll-behavior: contain;，把滚动行为彻底隔离。拾取容差方面，鼠标模式用默认值，触摸模式把点选半径调大一些，或者在交互层做「最近原子匹配」——点中的位置没有原子时，取投影距离最近且小于阈值的那个，用户体验会好很多。

#viewport { touch-action: none; /* 触摸事件交给渲染器，不交给页面滚动 */ overscroll-behavior: contain; /* 阻止拖动到底部时触发父级滚动 */ user-select: none; /* 拖动时不要选中文字 */ }

5.5 导出的图片全黑或糊成一团

现象：点导出，下载下来的 PNG 是纯黑背景，或者尺寸只有屏幕上那块小图，贴进文档后马赛克感严重。

原因：黑图是 WebGL 的preserveDrawingBuffer默认关闭导致的缓冲区失效；糊是因为直接用了屏幕尺寸的 canvas，没考虑设备像素比和导出分辨率。

解决：创建 viewer 时打开preserveDrawingBuffer；导出前按目标倍率临时调整尺寸，渲染一次再取图，取完还原。设备像素比window.devicePixelRatio在高分屏上可能是 2 甚至 3，导出时把它乘进去，图就清晰了。还有一个小细节：导出前把背景设成白色再还原，否则深色背景下贴进白底 Word 文档会显得很怪，这个细节在答辩时特别加分。

6. 验收与答辩：一份能照着走完的自检清单

这个项目最容易出的问题不是功能没做完，而是演示时才发现某个环节断了。我的习惯是交之前按一张固定清单从头走一遍，走通了才算完。

功能验收按十项走，每项都要有明确的通过标准，不能靠「好像能用」。

性能基线也建议提前测好记下来，答辩被问到「这个卡不卡」时有数可报：单链蛋白（约 2500 原子）加载到首帧控制在 1 秒内；复合物（约 3 万原子）首帧线条预览控制在 2 秒内、完整卡通模型控制在 5 秒内；表面渲染在 1 万原子以内可以开，超过就禁用。这些数字都是在自己机器上测的，报的时候要说明测试环境，别当成通用指标。

答辩演示的流程控制在三分钟，节奏比时长重要。开场十秒不要讲技术栈，直接打开一个含配体的复合物，先转一圈——画面动起来的那一刻，评委的注意力就抓住了。接着十五秒切样式，从卡通切到表面再切回球棍，顺口说一句「这里表面是溶剂可及表面，动画里的半透明层」。然后三十秒做一次测量：点两个原子报出距离，再点三个原子报出角度，这是全场最能体现实用性的部分。最后四十秒演示一次「打开一个空文件」，把错误提示亮出来，再说一句「这类异常我在入口就拦住了」，这比演示成功案例更有说服力，因为它证明你想过边界。

我最早做这类项目时，把所有力气花在把主流程做漂亮上，异常路径一个没管，结果第一次上台演示就翻了车——随手拖了个.txt进去，页面白屏、控制台一条红字，当场卡住三十秒不知道该说什么。从那以后我每次交付前都强制走一遍「故意喂错误数据」的流程：空文件、改后缀的图片、截断的 PDB、超大复合物，四个都试一遍，看提示能不能读懂。这个习惯救过我不止一次，也让这套分子查看器的异常分支比主流程还完整。希望帮到你。

本文还有配套的精品资源，点击获取