KaTeX mhchem 扩展完全指南在浏览器与 Node 中使用 \ce 与 \pu 渲染化学方程式【免费下载链接】KaTeXFast math typesetting for the web.项目地址: https://gitcode.com/GitHub_Trending/ka/KaTeXmhchem 是 KaTeX 官方 contrib 目录下的一组扩展它把 LaTeX 生态中著名的 mhchem 宏包 为骨架结合 contrib/mhchem/mhchem.js 的源码实现讲解如何在浏览器与 Node.js 中加载该扩展、如何书写化学式语法以及其内部“状态机解析 → TeX 生成”的工作原理。读完本文你将能在自己的 KaTeX 页面中直接渲染\ce{CO2 C - 2 CO}与\pu{123 kJ//mol}这类表达式。mhchem 扩展是什么KaTeX 的核心本身不包含任何化学命令——\ce、\pu、\tripledash等宏均来自本扩展。mhchem 扩展实现了 mhchem 宏包版本 3.3.0中\ce化学方程式与\pu物理量两大命令其代码由 MathJax 的extensions/TeX/mhchem.js改编而来两者在接口上针对 KaTeX 做了适配contrib/mhchem/mhchem.js 的文件头注释列出了与 MathJax 版本的主要差异接口改为供 KaTeX 调用而非 MathJax\rlap/\llap替换为\mathrlap/\mathllap若干处改用\raisebox代替\raise反应箭头全部改用 KaTeX 的可伸缩箭头extensible arrows渲染不再自行拼装不可伸缩箭头微调了\tripledash的垂直对齐。在 KaTeX 构建体系中mhchem 是独立的打包入口见 webpack.common.js{ name: contrib/mhchem, entry: ./contrib/mhchem/mhchem.js, },也就是说它默认不随katex.min.js一起加载需要单独引入。在浏览器中加载 mhchem由于扩展不属于 KaTeX 核心需在 HTML 页面中单独添加script标签。原文档给出的引入方式为将下面这一行写入页面的head中位置必须放在加载katex.js的那一行之后如果同时使用 auto-render 扩展则还要放在加载auto-render.js的那一行之前script defer srchttps://cdn.jsdelivr.net/npm/katex0.18.2/dist/contrib/mhchem.min.js integritysha384-fB8BH//9nBzROkMUsu/Dr35jWHIbnKesUo9rW0hfEgw8mZGnkAyBAjKX9F98OVuo crossoriginanonymous/script几个容易踩坑的细节脚本顺序即依赖顺序。mhchem 扩展通过修改全局的katex对象来注册宏源码中直接调用katex.__defineMacro(...)因此必须保证核心katex.js已先执行完毕defer属性必须保持一致。文档明确警告如果从这个标签上移除defer那么script src.../katex.min.js标签上的defer也必须一并移除否则脚本执行顺序会失控导致宏注册时katex尚未就绪与 auto-render 的协作。auto-render 会扫描页面中的文本节点并按定界符渲染数学mhchem 必须在它之前加载这样扫描到的\ce{...}才能被正确解析auto-render 的用法可参考 contrib/auto-render/README.md。当前仓库的 package.json 版本为 0.18.2与上述 CDN 地址中的版本号一致。在 Node.js 中使用 mhchemmhchem 扩展同样适用于服务端渲染。它通过修改katex模块的方式来注入宏因此只需在require(katex)之后再require一次扩展即可docs/node.md 给出了完整示例const katex require(katex); require(katex/contrib/mhchem); // modify katex module const html katex.renderToString(\\ce{CO2 C - 2 C0});要点是require(katex/contrib/mhchem)这一行的副作用就是向katex模块注册\ce、\pu、\tripledash宏之后调用katex.renderToString即可输出包含化学式的 HTML 字符串。这一机制也印证了扩展与核心解耦的设计——Node 场景下同样不需要额外引入katex.min.js。化学式语法\ce 与 \pumhchem 扩展支持两种命令分别对应两套内部状态机见 contrib/mhchem/mhchem.js 的chemParse入口与mhchemParser.stateMachines\ce{...}化学方程式。支持化学式、离子电荷、化学键、反应箭头、状态符号如(aq)、氧化态等\pu{...}物理量。支持带单位的数值如\pu{123 kJ//mol}。基础示例以下示例均出自仓库文档或可直接由源码状态机验证表达式说明\ce{CO2 C - 2 CO}化学方程式-渲染为反应箭头示例见 docs/node.md\ce{C6H5-CHO}下标与化学键-示例见 docs/support_table.md\pu{123 kJ//mol}分数形式的物理量示例见 docs/support_table.md\ce{H2O}最基本的化学式下标由源码中digits模式mhchem.js自动处理反应箭头源码中的箭头模式mhchem.js与texify._getArrow转换表mhchem.js一一对应支持以下箭头写法-、-单箭头-双向箭头--左右双箭头、\u21CC平衡符号可逆反应、向右/向左不平衡的可逆反应反应箭头还支持在箭头上方/下方标注条件通过[(...)]语法下方与^{...}/{...}上方实现源码中CMT模式mhchem.js负责解析[条件]标注。化学键\bond{...}命令与直接的-、、#、~等符号都可用于表示化学键支持类型在texify._getBondmhchem.js中可查包括-单键、双键、#三键~波浪键\tripledash、~-、~、~--、-~-等组合键...、....点键、-、-配位方向键其中\tripledash宏在文件顶部定义mhchem.js用于渲染波浪键的三横线符号。状态符号、氧化态与更多结构状态符号(aq)、(g)、(l)、(s)等小写缩写会被识别为聚集状态源码state of aggregation $模式mhchem.js氧化态罗马数字形式的氧化态如\ce{Fe^{II}}由oxidation状态机与oxidation-output动作mhchem.js处理分数与上下标\frac、\overset、\underset、\underbrace、\color等命令在ce状态机的转移表中有对应分支mhchem.js生成 TeX 时分别输出为对应的 LaTeX 结构mhchem.js。关于 \cf 的说明原文档特别提醒早期版本的mhchem.sty用\cf表示化学式、\ce表示化学方程式后来\cf已被\ce取代并弃用。本扩展只支持\ce\cf在 docs/support_table.md 中标记为 Not supported。如确有需要可自行定义宏将\cf映射到\ce。源码剖析从输入到输出的完整链路mhchem 扩展的核心代码全部位于单个文件 contrib/mhchem/mhchem.js约 1695 行整体分三层第一层宏注册文件顶部通过 KaTeX 公开的__defineMacro注册三个宏mhchem.jskatex.__defineMacro(\\ce, function(context) { return chemParse(context.consumeArgs(1)[0], ce) }); katex.__defineMacro(\\pu, function(context) { return chemParse(context.consumeArgs(1)[0], pu); }); katex.__defineMacro(\\tripledash, {\\vphantom{-}\\raisebox{2.56mu}{...}});__defineMacro是 KaTeX 在 katex.ts 与 katex.ts 中对外暴露的宏注册接口。chemParse会把 KaTeX 传入的参数 token 序列重新拼接为字符串再交给状态机解析mhchem.js。第二层状态机解析mhchemParsermhchemParser.go是递归下降的状态机主循环mhchem.js。解析器为不同场景准备了多套状态机stateMachines对象mhchem.jsce\ce主解析器a、bd、pq、o、q、D、dq、qD、qd、oxidation化学式的量、上标、下标、元素、氧化态等子解析器tex-math、tex-math tight嵌入的普通数学模式pu、pu-2、pu-9,9\pu物理量解析器含千分位分隔、分数、10^n科学计数法、//分数线等。每个状态机由一张“转移表”驱动根据当前状态与输入字符匹配预定义的模式patterns执行相应动作actions然后进入下一状态。createTransitionsmhchem.js负责把声明式的转移表编译成按状态索引的结构并支持*通配状态与a|b多状态简写。解析过程中还内置了看门狗计数防止无限循环mhchem.js。解析产物是一棵由chemfive化学五元组量、左上标、左下标、元素、右下标、右上标、arrow、bond、operator等节点组成的中间结构例如output动作mhchem.js会一次性输出一个包含a/b/p/o/q/d六字段的chemfive节点。第三层TeX 生成texifytexify.go遍历中间结构将其翻译为 KaTeX 能直接解析的 TeX 字符串mhchem.js。_go2是一个大的switch针对每种节点类型生成对应 TeXchemfive用{\vphantom{X}}、^{\hphantom{...}}、\mathllap、\smash等技巧精确控制上下标位置与基线对齐rm/text输出\mathrm{...}或\text{...}bond查_getBond表输出键符arrow输出\xrightarrow/\xleftarrow等 KaTeX 可伸缩箭头mhchem.js上方/下方标注通过可选参数与花括号参数实现operator查_getOperator表mhchem.js为、-、、、等运算符生成带间距的{}{}形式。最终生成的 TeX 字符串返回给 KaTeX 的宏展开器再由 KaTeX 核心完成后续的解析与渲染。这就是\ce{...}从输入到 HTML 输出的完整链路。构建与浏览器兼容性如果需要从源码构建该扩展的产物KaTeX 仓库的打包配置已包含 mhchem 入口webpack.common.js构建后会在 dist 下生成contrib/mhchem.js、contrib/mhchem.min.js与contrib/mhchem.mjs目录结构见 docs/browser.md可按需选用script标签或 ESM 导入方式。关于兼容性原文档说明该扩展已在 Chrome、Firefox、Opera 与 Edge 上完成测试。需要留意的是\ce的渲染依赖 KaTeX 的可伸缩箭头、\mathllap/\mathrlap、\vphantom/\hphantom/\smash等排版原语因此其渲染效果与所用 KaTeX 核心版本相关建议搭配当前仓库对应的 0.18.x 版本使用。小结mhchem 扩展以极小的接入成本一个script标签或一行require为 KaTeX 补齐了化学式排版能力。理解其“宏注册 → 状态机解析 → TeX 生成”的三层架构有助于在遇到\ce/\pu语法异常时快速定位问题语法支持范围查patterns与stateMachines输出样式查texify._go2的 switch 分支。更多语法细节含可交互演示可参阅 mhchem 官方手册仓库内的 docs/support_table.md 也收录了\ce、\pu的渲染示例供对照验证。【免费下载链接】KaTeXFast math typesetting for the web.项目地址: https://gitcode.com/GitHub_Trending/ka/KaTeX创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考