---
title: "数学与公式"
description: "在整个 DOCX 转换流程中如何处理行内和块级数学公式，包括 OMML 导入限制和基于 LaTeX 的导出。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/content-types/structures-and-media/math-equations"
---

# 数学与公式

在整个 DOCX 转换流程中如何处理行内和块级数学公式，包括 OMML 导入限制和基于 LaTeX 的导出。

Word 将公式存储为 OMML（Office Math Markup Language）。Tiptap 使用由 KaTeX 渲染的 LaTeX 表示法。目前转换管道仅支持导出，不支持导入。

## 你需要什么

- **扩展：** `@tiptap/extension-mathematics`（不在 StarterKit 中）
- **依赖：** `katex`（`^0.16.4`）用于渲染

```bash
npm install @tiptap/extension-mathematics katex
```

## 支持概览

|      | 导入  | 编辑器              | 导出               |
| ---- | --- | ---------------- | ---------------- |
| 行内公式 | 不支持 | 支持（`inlineMath`） | 支持（LaTeX 转 OMML） |
| 块级公式 | 不支持 | 支持（`blockMath`）  | 支持（LaTeX 转 OMML） |

## 导入

无论是在 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md) 还是在 [REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md) 中，公式都不会被导入。

> **公式不会从 DOCX 中导入:**
>
> 导入转换器没有 OMML 处理能力。DOCX XML 中的数学元素不会被解析器识别，也不会包含在输出中。输出里不会出现任何数学节点。如果你的文档包含公式，它们将在导入后的 Tiptap 文档中缺失。

DOCX 导入转换器不包含任何 OMML 解析。当解析器在文档 XML 中遇到数学标记时，它不会识别这些元素，并会完全跳过它们。不会生成任何 `inlineMath` 或 `blockMath` 节点。

如果你的工作流需要从 DOCX 导入公式，你需要从头构建 OMML 解析以及 OMML 到 LaTeX 的转换。导入转换器中没有现成的数学基础设施可供扩展。

## 编辑器渲染

[`Mathematics`](https://tiptap.zhcndoc.com/editor/extensions/nodes/mathematics.md) 扩展提供两种节点类型。它不包含在 StarterKit 中。

该扩展提供：

- **`inlineMath`** 在文本中渲染。输入 `$$E = mc^2$$` 可通过输入规则创建。
- **`blockMath`** 作为独立块渲染。输入 `$$$\sum_{i=1}^{n} x_i$$$` 可通过输入规则创建。

二者都将内容作为 `latex` 属性中的 LaTeX 字符串存储，并使用 KaTeX 渲染。

```ts
import { Mathematics } from '@tiptap/extension-mathematics'
import 'katex/dist/katex.min.css'

const editor = new Editor({
  extensions: [
    StarterKit,
    Mathematics,
  ],
})
```

如果没有 Mathematics 扩展，数学节点不会被 schema 识别。请参见 [无效 schema 指南](https://tiptap.zhcndoc.com/guides/invalid-schema.md)。

## 导出

可使用 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) 或 [REST API](https://tiptap.zhcndoc.com/conversion/export/docx/rest-api.md) 导出数学公式。两者处理数学的方式完全相同，都会将 LaTeX 转换为 OMML。

导出转换器会读取 `inlineMath` 和 `blockMath` 节点中的 `latex` 属性，并将 LaTeX 转换为与 OMML 兼容的数学组件，以用于 DOCX 文件。

支持的 LaTeX 特性：

| LaTeX                           | OMML 输出                 |
| ------------------------------- | ----------------------- |
| `\frac{a}{b}`                   | 分数                      |
| `\sqrt{x}`, `\sqrt[n]{x}`       | 根式                      |
| `x^{2}`                         | 上标                      |
| `x_{i}`                         | 下标                      |
| `\begin{matrix}...\end{matrix}` | 矩阵                      |
| 希腊字母、运算符、箭头                     | 通过 200+ 符号映射转换为 Unicode |

如果某个 LaTeX 字符串无法解析，转换器会回退为普通数学运行，并保留原始 LaTeX 文本。

> **LaTeX 覆盖范围并非穷尽:**
>
> 转换器支持常见的数学表示法。超出 `matrix` 的自定义环境、自定义宏或复杂对齐等高级 LaTeX 特性可能无法完美转换。在依赖导出用于生产工作流之前，请先测试你的具体公式。

`blockMath` 节点会导出为一个包含数学元素的独立段落。`inlineMath` 节点会作为父段落中的数学元素与普通文本运行一起导出。