数学公式(KaTeX)
编辑器内置 KaTeX 数学公式:两个原子节点 mathInline(行内)和 mathBlock(块级),LaTeX 源码保存在 latex 属性中。
输入方式
- 输入规则:正文键入
$x^2$转为行内公式;整段键入$$x$$(或分隔符独占行的多行形式)转为块级公式。内容非空、不含$,起始$前与结束$后不贴字母数字,规避「5$ and 3$」类货币误判;需要货币语义用\$转义。 - slash command / 工具栏:
/公式(或拼音gongshi/latex)与工具栏「公式」按钮(∑ 图标)打开插入弹层,输入框下方有「行内公式」勾选项(默认不勾 = 块级),实时预览确认后才插入文档。
行内公式最快路径仍是键入 $...$;弹层勾选项是给不知道语法或用中文输入法的用户的兜底入口。
编辑与删除
通过工具栏 ∑ 按钮或 /公式 插入公式走先弹层、确认才落文档的流程(与插入链接一致):弹层预填示例公式(E = mc^2,可直接改)、输入框下方可勾选「行内公式」、带实时预览与错误提示,点「确定」才把用户输入的公式插入文档并自动选中;点「取消」不会在文档里留下任何占位公式。编辑已有公式时勾选项按当前类型初始化——改动勾选即原地转换类型(行内↔块级,单步撤销;块级转行内会替换为含公式的段落)。点击已有公式选中节点,气泡菜单提供「编辑公式」(打开同一弹层,预填当前源码)与「删除公式」。弹层打开期间编辑器失焦,确认时按打开时保存的节点位置回写,不会误更新到其他节点。
只读和预览状态隐藏气泡菜单。
Markdown 往返
块级公式按标准 $$ 块导入导出(独占行,内容可含换行):
$$
\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
$$行内公式导出为 $latex$ 源码兜底;导入侧的行内 $ 识别(货币误判防护)在后续版本提供。HTML / JSON 始终完整保留公式节点。
打印 / PDF 导出
打印副本中的公式替换为原生 MathML(浏览器直接渲染),不依赖 KaTeX CSS 和字体文件,离线环境也可正确导出。
样式引入
KaTeX 按需动态加载,公式渲染样式随 adapter 单独提供,在 style.css 之外多引入一行:
import 'tiptap-vue-pro-element-plus/style.css'
import 'tiptap-vue-pro-element-plus/katex.css' // 含 KaTeX 字体,浏览器按需加载不需要公式能力时可不引入(节点会以源码文本降级显示),或通过扩展开关关闭:
const ctx = useProEditor({ /* ... */ })
// useProEditor 内部: createEditorExtensions({ math: false })注意:传入自定义 extensions 会完全覆盖默认扩展包,此时需自行加入 MathInline / MathBlock(从 tiptap-vue-pro-core 导入),公式相关命令与 Markdown 往返才可用。
怎么写公式:常用语法
编辑弹层底部有可折叠的「常用语法」面板,片段点击即插入光标处;完整语法见 KaTeX 支持列表。
| 想写 | 语法 |
|---|---|
| 上标 x² / 下标 a₁ | x^2 / a_1 |
| 分数 a/b | \\frac{a}{b} |
| 根号 | \\sqrt{x} |
| 求和 Σ / 积分 ∫ / 极限 | \\sum_{i=1}^{n} / \\int_a^b / \\lim_{x \\to 0} |
| 希腊字母 α β π | \\alpha \\beta \\pi |
| ± × ∞ ∂ ≤ ≥ ≠ | \\pm \\times \\infty \\partial \\leq \\geq \\neq |
| 矩阵 | \\begin{pmatrix} a & b \\\\ c & d \\end{pmatrix} |
| 分段函数 | \\begin{cases} x^2, & x ≥ 0 \\\\ -x, & x < 0 \\end{cases} |
| 多行等号对齐 | \\begin{aligned} a &= b \\\\ c &= d \\end{aligned} |
规则只有三条:命令以反斜杠 \\ 开头;花括号 { } 给命令分组传参;结构环境里 \\ 换行、& 对齐。
安全与降级
trust 固定为 false(\href 等危险命令不产生链接输出),throwOnError: true 由渲染层捕获:非法 LaTeX 在节点内显示源码与错误提示,不影响编辑器其他内容。maxExpand 保留默认上限防止宏展开资源耗尽。宿主可通过 ProEditorOptions.math 透传安全的 katexOptions(如自定义 macros)或注入自定义渲染函数(render)。