配置 KaTeX

本指南结合 KaTeX 官方 API、自动渲染扩展及扩展库内容，总结性翻译关键概念，保留所有代码块并添加必要注释。URL 已转换为 Markdown 链接格式，结尾提供总结。

KaTeX API

KaTeX 提供浏览器和服务器端渲染功能，支持数学公式的动态处理。

浏览器渲染

使用 katex.render 方法，传入 TeX 表达式和目标 DOM 元素：

// 渲染数学公式到指定元素，启用错误抑制
katex.render("c = \\pm\\sqrt{a^2 + b^2}", element, {
  throwOnError: false  // 错误时不抛出异常，显示红色源码
});

为避免转义问题，可用 String.raw：

// 使用 String.raw 简化反斜杠处理
katex.render(String.raw`c = \pm\sqrt{a^2 + b^2}`, element, {
  throwOnError: false
});

服务器端渲染

生成 HTML 字符串使用 katex.renderToString：

// 将数学公式渲染为 HTML 字符串
var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}", {
  throwOnError: false  // 返回包含 katex 类的 HTML
});

错误处理

设置 throwOnError: false 可使无效输入显示为红色 TeX 源码（带悬停错误信息）。未设置时，无效 LaTeX 会抛出 katex.ParseError 异常。详见 https://katex.org/docs/error.html。

持久宏配置

宏定义（如 \gdef）需共享 macros 对象以保持状态：

const macros = {};  // 创建共享宏对象
for (let element of mathElements) {
  katex.render(element.textContent, element, {
    throwOnError: false,
    macros  // 传递同一对象，确保宏定义持久化
  });
}

安全警告：持久宏可改变 KaTeX 行为（如重定义命令），仅限可信任环境（如单用户消息内），避免跨多用户使用。

自动渲染扩展

此扩展自动检测并渲染文本中的数学公式，无需手动调用。

基本用法

在页面中包含 KaTeX CSS 和 JS，并使用自动渲染脚本：

<!-- 引入 KaTeX 样式 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.css" integrity="sha384-5TcZemv2l/9On385z///+d7MSYlvIEw9FuZTIdZ14vJLqWphw7e7ZPuOiCHJcFCP" crossorigin="anonymous">
<!-- 引入 KaTeX 主脚本 -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.js" integrity="sha384-cMkvdD8LoxVzGF/RPUKAcvmm49FQ0oxwDF3BGKtDXcEc+T1b2N+teh/OJfpU0jr6" crossorigin="anonymous"></script>
<!-- 自动渲染脚本，页面加载后执行 -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/contrib/auto-render.min.js" integrity="sha384-hCXGrW6PitJEwbkoStFjeJxv+fSOOQKOPbJxSfM6G5sWZjAyWhXiTIIAmQqnlLlh" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>

自定义选项

通过 DOMContentLoaded 事件定制渲染：

<!-- 同上引入样式和脚本 -->
<script>
document.addEventListener("DOMContentLoaded", function() {
  renderMathInElement(document.body, {
    delimiters: [  // 定义数学公式分隔符
      {left: '$$', right: '$$', display: true},   // 显示模式公式
      {left: '$', right: '$', display: false},    // 行内模式公式
      {left: '\\(', right: '\\)', display: false}, // LaTeX 行内
      {left: '\\[', right: '\\]', display: true}   // LaTeX 显示
    ],
    throwOnError: false,  // 抑制渲染错误
    ignoredTags: ["script", "noscript", "style", "textarea", "pre", "code", "option"],  // 忽略的标签
    preProcess: (math) => math.trim()  // 预处理函数示例
  });
});
</script>

ECMAScript 模块支持

使用模块语法引入：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.css" integrity="sha384-5TcZemv2l/9On385z///+d7MSYlvIEw9FuZTIdZ14vJLqWphw7e7ZPuOiCHJcFCP" crossorigin="anonymous">
<script type="module">
import renderMathInElement from "https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/contrib/auto-render.mjs";
renderMathInElement(document.body);  // 直接渲染
</script>

API 详解

renderMathInElement(elem, options) 函数参数：

  • elem: HTML DOM 元素，递归搜索其文本节点。
  • options: 配置对象，包括：
    • delimiters: 分隔符列表（顺序敏感），如 [{left: "$$", right: "$$", display: true}]。
    • ignoredClasses: 忽略的 CSS 类（默认无）。
    • errorCallback: 错误回调函数（默认 console.error）。
    • macros: 共享宏对象，类似 API 部分。

扩展与库

KaTeX 提供官方扩展和第三方集成库。

KaTeX 官方扩展

  • Auto-render: 自动渲染文本数学公式（#自动渲染扩展-基于链接2）。
  • Copy-tex: 复制渲染元素时保留 LaTeX 源码，访问 https://katex.org/docs/copy-tex.html。
  • Custom Script Type: 自动渲染 type=math/tex 脚本标签。
  • mhchem: 简化化学方程式渲染，见 https://katex.org/docs/mhchem.html。

第三方库

  • AsciiMath: 通过 https://github.com/runarberg/asciimath2tex 转换 AsciiMath 为 TeX。
  • Android: https://github.com/lingarajsankaravelu/KatexView 安卓渲染库。
  • Angular2+: https://github.com/garciparedes/ng-katex Angular 模块。
  • Canvas: https://github.com/georgjaehnig/canvas-latex 支持 Canvas 渲染。
  • iOS:
    • https://github.com/andylokandy/Katex-iOS UIView 集成。
    • https://github.com/rojer95/KatexUtils CocoaPods 兼容库。
  • Jekyll: https://github.com/linjonh/JekTex Jekyll 插件，支持 GitHub Pages。
  • React:
    • https://github.com/zzish/react-latex 基于 KaTeX 的组件。
    • https://github.com/talyssonoc/react-katex 数学公式渲染器。
  • Ruby: https://github.com/glebm/katex-ruby Rails/Sprockets 集成。
  • Rust: https://github.com/xu-cheng/katex-rs 服务端渲染绑定。
  • Sphinx: https://github.com/hagenw/sphinxcontrib-katex Sphinx 扩展。
  • Vue: https://github.com/lucpotage/vue-katex Vue 插件。
  • Web Components:
    • https://github.com/justjavac/katex-element 自定义元素实现。
    • https://github.com/rojer95/katex-expression Stencil 构建组件。
  • 微信小程序: https://github.com/rojer/katex-mini 微信集成库。

总结

核心要点总结

  • KaTeX API：支持浏览器（katex.render）和服务端（katex.renderToString）渲染，通过 throwOnError: false 处理错误，持久宏需共享对象以确保状态一致 🛡️。
  • 自动渲染扩展：使用 renderMathInElement 自动检测分隔符（如 $$ 或 $），可定制选项并通过事件触发，简化页面集成 🔍。
  • 扩展与库：KaTeX 提供官方扩展（如 auto-render 和 mhchem），并有丰富第三方库支持多平台（React、Vue、Android 等），提升开发灵活性 ⚙️。 建议结合具体场景选择集成方式，优先使用官方扩展确保兼容性 💡。
最后更新: