Kekule.js 完整使用手册（中文完整版）

一、Kekule.js 概述1. 简介Kekule.js 是MIT 开源的纯前端化学信息学 JS 工具库无后端依赖可在浏览器 /electron 运行核心能力分子、反应式数据模型原子、键、环、手性、立体化学多格式 IOSMILES、CML、MDL Mol/Mol2000、Kekule JSON/XML、InChI扩展2D/3D 分子渲染、骨架式 / 球棍 / 填充模型切换可视化组件Viewer只读展示、Composer交互式绘图编辑器子结构检索、分子对比、芳香环识别、2D 自动布局快捷键、撤销重做、复制粘贴、自定义工具栏2. 模块划分模块核心功能Core化学基础对象Atom、Bond、Molecule、Reaction、坐标、立体结构IO分子格式读写、字符串 / 文件 / URL 加载导出Render2D/3D 渲染器样式、显示模型配置Widget基础 UI 控件弹窗、下拉、表格ChemWidget化学专用组件Viewer、Composer、周期表EditorComposer 编辑器绘图工具逻辑Extra扩展InChI、OpenBabel 适配器、自动 2D 布局3. 官方文档地址教程https://partridgejiang.github.io/Kekule.js/documents/tutorial/主页https://partridgejiang.github.io/Kekule.js/二、安装与引入3 种方式方式 1CDN 直接引入快速 demo 推荐!-- 样式必须先引入 -- link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/kekule/dist/themes/default/kekule.css/ !-- 核心JS -- script srchttps://cdn.jsdelivr.net/npm/kekule/dist/kekule.min.js/script方式 2NPM 工程Vue/React/ 原生工程npm install --save kekuleES Moduleimport { Kekule } from kekule // 使用Viewer/Composer必须导入主题样式 import kekule/theme/default console.log(Kekule.VERSION)CommonJSconst { Kekule } require(kekule) require(kekule/theme/default)方式 3本地文件部署将dist/kekule.min.js、dist/themes/复制到项目静态目录link relstylesheet href./static/kekule/themes/default/kekule.css/ script src./static/kekule/kekule.min.js/script三、基础分子对象操作Core 模块1. 手动创建分子环氧乙烷示例// 1. 创建分子容器 const mol new Kekule.Molecule() // 2. 创建原子链式设置元素、2D坐标 const C1 new Kekule.Atom().setSymbol(C).setCoord2D({x:-0.4, y:0.23}) const C2 new Kekule.Atom().setSymbol(C).setCoord2D({x:0.4, y:0.23}) const O1 new Kekule.Atom().setSymbol(O).setCoord2D({x:0, y:-0.46}) // 3. 原子加入分子 mol.appendNode(C1) mol.appendNode(C2) mol.appendNode(O1) // 4. 创建化学键键级1单键、2双键、3三键 const b1 new Kekule.Bond().setBondOrder(1).setConnectedObjs([C1, C2]) const b2 new Kekule.Bond().setBondOrder(1).setConnectedObjs([C2, O1]) const b3 new Kekule.Bond().setBondOrder(1).setConnectedObjs([O1, C1]) mol.appendNode(b1) mol.appendNode(b2) mol.appendNode(b3)2. 遍历原子 / 键、提取分子式// 遍历所有原子 mol.eachAtom(atom{ console.log(atom.getSymbol(), atom.getCoord2D()) }) // 遍历所有键 mol.eachBond(bond{ console.log(键级, bond.getBondOrder()) }) // 获取分子式 const formula mol.getFormula() console.log(分子式, formula)四、IO 模块分子导入导出核心支持格式smiles/cml/mol/mol2000/kekule-json/kekule-xml1. 从字符串加载分子// SMILES转分子对象 const smi CCO const ethanol Kekule.IO.loadFormatData(smi, smiles) // CML字符串加载 const cmlStr cml xmlnshttp://www.xml-cml.org/schemamolecule idm1//cml const emptyMol Kekule.IO.loadFormatData(cmlStr, cml)2. 分子导出为字符串const mol ethanol // 导出SMILES const smiOut Kekule.IO.saveFormatData(mol, smiles) // 导出CML const cmlOut Kekule.IO.saveFormatData(mol, cml) // 导出Mol文件 const molFile Kekule.IO.saveFormatData(mol, mol)3. 远程 URL 加载分子异步Kekule.IO.loadUrlData(./data/ethanol.mol, (mol, success){ if(success){ console.log(加载成功, mol) }else{ console.error(文件加载失败) } })4. 本地文件上传加载File 对象const fileInput document.getElementById(file) fileInput.onchange e{ const file e.target.files[0] Kekule.IO.loadFileData(file, (mol, ok){ if(ok) viewer.setChemObj(mol) }) }五、ChemWidget.Viewer只读分子查看器用于展示分子、支持缩放 / 平移 / 3D 旋转不可编辑。1. 快速创建 Viewerdiv idviewerWrap stylewidth:700px;height:450px;border:1px solid #ccc;/div// 实例化挂载到DOM const viewer new Kekule.ChemWidget.Viewer(document.getElementById(viewerWrap)) // 设置宽高 viewer.setDimension(700px, 450px) // 加载乙醇分子 const mol Kekule.IO.loadFormatData(CCO, smiles) viewer.setChemObj(mol)2. 关键配置属性// 2D/3D切换 viewer.setRenderType(Kekule.Render.rendererType.R2D) // viewer.setRenderType(Kekule.Render.rendererType.R3D) // 2D显示模式骨架式/简式 viewer.setMoleculeDisplayType(Kekule.Render.Molecule2DDisplayType.SKELETAL) // viewer.setMoleculeDisplayType(Kekule.Render.Molecule2DDisplayType.CONDENSED) // 3D模型线框/棍状/球棍/空间填充 // WIRE / STICKS / BALL_STICK / SPACE_FILL viewer.setMoleculeDisplayType(Kekule.Render.Molecule3DDisplayType.BALL_STICK) // 启用顶部工具栏 viewer.setEnableToolbar(true) // 自定义工具栏按钮 viewer.setToolButtons([zoomIn,zoomOut,resetView,switch2D3D]) // 鼠标交互缩放平移 viewer.setEnableMouseControl(true) // 允许双击打开编辑器 viewer.setEnableEdit(false) // 自适应尺寸 viewer.setAutoSize(false)六、Editor.Composer交互式分子绘图编辑器最常用网页版化学结构式绘制面板支持手绘、快捷键、撤销、复制粘贴。1. 创建编辑器div idcomposerBox stylewidth:800px;height:500px;border:1px solid #999;/div// 创建编辑器实例 const composer new Kekule.Editor.Composer() // 设置尺寸并挂载DOM composer.setDimension(800px,500px) composer.appendToElem(document.getElementById(composerBox)) // 自定义顶部工具栏 composer.setCommonToolButtons([ undo,redo,cut,copy,paste, zoomIn,zoomOut,reset,clearAll ]) // 初始加载分子可选 const initMol Kekule.IO.loadFormatData(C6H6, smiles) composer.setChemObj(initMol)2. 获取编辑器内分子、导出格式// 获取当前画布分子对象 const currentMol composer.getChemObj() // 导出SMILES const smi Kekule.IO.saveFormatData(currentMol, smiles) console.log(绘制结果SMILES, smi) // 导出CML const cml Kekule.IO.saveFormatData(currentMol, cml)3. Composer 全局快捷键编辑器获焦点生效绘图快捷键按键功能A添加碳原子O/N/S/P添加氧 / 氮 / 硫 / 磷1/2/3单键 / 双键 / 三键W实楔键向前立体ShiftW虚楔键向后立体T任意单键编辑通用快捷键快捷键功能CtrlA全选原子 / 键Delete / Backspace删除选中对象CtrlZ撤销CtrlShiftZ / CtrlY重做CtrlC复制CtrlX剪切CtrlV粘贴鼠标滚轮缩放画布七、渲染样式自定义1. 修改原子、键颜色// 获取渲染配置 const renderCfg viewer.getRenderConfig() // 碳元素颜色 renderCfg.elementColors[C] #222222 // 氧红色 renderCfg.elementColors[O] #ff3333 // 键粗细 renderCfg.bondLineWidth 2 viewer.setRenderConfig(renderCfg)2. 隐藏氢原子骨架图常用const renderCfg composer.getRenderConfig() renderCfg.showHydrogen false composer.setRenderConfig(renderCfg)八、分子高级功能1. 子结构检索// 母分子乙醇 CCO const parent Kekule.IO.loadFormatData(CCO,smiles) // 子结构模板羟基 -OH const subTemplate Kekule.IO.loadFormatData(O,smiles) // 执行子结构匹配 const matcher new Kekule.MolSearch.SubstructureMatcher(parent) const matchResult matcher.match(subTemplate) console.log(匹配数量, matchResult.length)2. 分子相等对比const mol1 Kekule.IO.loadFormatData(CCO,smiles) const mol2 Kekule.IO.loadFormatData(OCC,smiles) const isSame Kekule.MolCompare.isIsomorphic(mol1, mol2) console.log(分子同分等价, isSame) // true3. 芳香环自动识别const benzene Kekule.IO.loadFormatData(c1ccccc1,smiles) const rings benzene.getRings() rings.forEach(ring{ if(ring.isAromatic()) console.log(芳香环, ring.getAtomCount()) })九、Web Component 标签式使用零 JS 初始化无需写 JSDOM 属性直接创建 Viewer/Composer!-- Viewer查看器 -- div stylewidth:600px;height:400px data-widgetKekule.ChemWidget.Viewer data-render-typeR2D data-chem-dataCCO data-chem-formatsmiles /div !-- Composer编辑器 -- div stylewidth:800px;height:500px data-widgetKekule.Editor.Composer data-tool-buttonsundo,redo,copy,paste,zoomIn,zoomOut /div script // 自动初始化页面所有data-widget组件 Kekule.Widget.autoBindWidgets() /script十、React/Vue 集成说明Reactkekule-react 封装npm install kekule kekule-reactimport { Kekule } from kekule import kekule/theme/default import { KekuleReact } from kekule-react // 包装编辑器组件 const Composer KekuleReact.Utils.wrapWidget(Kekule.Editor.Composer) function MolEditor(){ return ( Composer style{{width:800px, height:500px}} toolButtons{[undo,redo,clearAll]} onChange{(widget){ const mol widget.getChemObj() const smi Kekule.IO.saveFormatData(mol, smiles) console.log(smi) }} / ) }Vue 原生封装思路在mounted生命周期实例化 Composer/ViewerbeforeUnmount销毁组件释放内存通过 ref 获取 DOM 容器挂载编辑器十一、常见问题与排错编辑器空白、样式丢失未引入kekule.css必须先加载样式再加载 JS。SMILES 加载失败检查 SMILES 合法性或改用mol/cml格式测试。快捷键不生效点击编辑器画布获取焦点后再按快捷键。跨域无法加载本地 mol 文件本地文件协议file://会触发 AJAX 跨域需部署本地 web 服务。3D 渲染卡顿降低分子原子数量切换 WIRE 线框模式。NPM 打包报错找不到 theme 确认导入路径import kekule/theme/default部分打包器需配置静态资源复制。十二、完整最小可运行 Demo复制直接打开!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleKekule Demo/title link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/kekule/dist/themes/default/kekule.css/ /head body h3分子编辑器/h3 div ideditBox stylewidth:800px;height:480px;border:1px solid #666;/div button idexportBtn导出SMILES/button div idresult/div script srchttps://cdn.jsdelivr.net/npm/kekule/dist/kekule.min.js/script script // 创建编辑器 const composer new Kekule.Editor.Composer() composer.setDimension(800px,480px) composer.appendToElem(document.getElementById(editBox)) composer.setCommonToolButtons([undo,redo,copy,paste,zoomIn,zoomOut,clearAll]) // 导出按钮 document.getElementById(exportBtn).onclick (){ const mol composer.getChemObj() const smi Kekule.IO.saveFormatData(mol, smiles) document.getElementById(result).innerText SMILES smi } // 初始加载苯 const benzene Kekule.IO.loadFormatData(c1ccccc1, smiles) composer.setChemObj(benzene) /script /body /html