fix: rm other attr in mathml

2026-02-04 16:12:22 +08:00
parent 35419b2102
commit f1229483bf
3 changed files with 483 additions and 8 deletions
--- a/docs/WORD_MATHML_GUIDE.md
+++ b/docs/WORD_MATHML_GUIDE.md
@@ -0,0 +1,204 @@
+# MathML 导入 Word 完整指南
+
+## 问题诊断
+
+如果 MathML 无法在 Word 中渲染，通常是以下原因：
+
+### 1. **MathML 格式问题**
+- ❌ 包含 `<semantics>` 和 `<annotation>` 包装器
+- ❌ 使用 `display="inline"` 而不是 `display="block"`
+- ❌ 缺少 `xmlns` 命名空间
+- ❌ 使用 HTML 实体编码而不是实际字符
+
+### 2. **Word 粘贴方法不正确**
+- ❌ 直接粘贴到正文
+- ❌ 使用"选择性粘贴"
+- ❌ 粘贴位置不对
+
+## 已修复的问题
+
+我们的代码现在会自动：
+✅ 移除 `<semantics>` 和 `<annotation>` 包装器
+✅ 设置 `display="block"`
+✅ 添加正确的 `xmlns` 命名空间
+✅ 解码 Unicode 实体为实际字符
+
+## Word 中正确的粘贴方法
+
+### 方法 1：使用 MathType（推荐）✨
+
+如果你安装了 MathType：
+
+1. 复制 MathML 内容
+2. 在 Word 中：**插入** → **对象** → **MathType 公式**
+3. 在 MathType 中：**编辑** → **粘贴 MathML**
+4. 点击"确定"
+
+### 方法 2：使用 Word 内置公式编辑器
+
+#### 选项 A：Alt 文本方法（最可靠）
+
+1. 在 Word 中：**插入** → **公式**
+2. 输入任意内容（如 `x`）
+3. 选中公式，右键 → **公式选项** → **另存为新公式**
+4. 取消，返回文档
+5. 右键公式 → **编辑替换文本**
+6. 将 MathML 粘贴到替换文本框
+7. 按 Enter
+
+#### 选项 B：XML 方法（需要开发者模式）
+
+1. **文件** → **选项** → **自定义功能区**
+2. 勾选"开发工具"
+3. **开发工具** → **XML 映射**
+4. 粘贴 MathML
+
+#### 选项 C：宏方法（高级）
+
+使用 VBA 宏：
+
+```vba
+Sub InsertMathML()
+    Dim mathML As String
+    mathML = "<math>...</math>" ' 粘贴你的 MathML
+    
+    Selection.Range.InsertXML mathML
+End Sub
+```
+
+### 方法 3：使用在线工具转换
+
+1. 访问 https://www.mathcha.io/
+2. 粘贴 MathML
+3. 导出为 Word 格式
+
+## 测试你的 MathML
+
+运行诊断工具：
+
+```bash
+python test_mathml_word_compatibility.py
+```
+
+这会检查：
+- ✓ 命名空间是否正确
+- ✓ Display 属性
+- ✓ 是否有 semantics 包装器
+- ✓ Unicode 实体
+
+## 示例：正确的 MathML 格式
+
+```xml
+<math display="block" xmlns="http://www.w3.org/1998/Math/MathML">
+  <mrow>
+    <mi>γ</mi>
+    <mo>=</mo>
+    <mn>22.2</mn>
+    <mo>,</mo>
+    <mi>c</mi>
+    <mo>=</mo>
+    <mn>30.4</mn>
+  </mrow>
+</math>
+```
+
+**不要有：**
+```xml
+<math>
+  <semantics>    ❌ Word 可能不识别
+    <mrow>...</mrow>
+    <annotation>...</annotation>    ❌ Word 不需要
+  </semantics>
+</math>
+```
+
+## API 使用
+
+### 获取 Word 兼容的 MathML
+
+```bash
+curl -X POST "http://localhost:8000/api/v1/image/ocr" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "image_base64": "...",
+    "model_name": "mineru"
+  }'
+```
+
+响应中的 `mathml` 字段已经过优化，可以直接用于 Word。
+
+### 如果还是不工作
+
+1. **检查 Word 版本**
+   - Word 2010+ 支持 MathML
+   - Word Online 支持有限
+
+2. **检查 MathML 内容**
+   ```bash
+   python test_mathml_word_compatibility.py
+   ```
+
+3. **尝试 OMML 格式（Word 原生）**
+   ```bash
+   curl -X POST "http://localhost:8000/api/v1/convert/latex-to-omml" \
+     -H "Content-Type: application/json" \
+     -d '{"latex": "\\gamma = 22.2"}'
+   ```
+   
+   OMML 是 Word 的原生格式，兼容性最好。
+
+## 为什么 OMML 更好？
+
+| 格式 | 用途 | Word 兼容性 |
+|------|------|------------|
+| **MathML** | Web 标准、跨平台 | ⭐⭐⭐ 需要转换 |
+| **OMML** | Word 原生格式 | ⭐⭐⭐⭐⭐ 完美 |
+
+**建议**：
+- 手动粘贴 → 使用 MathML
+- 编程生成 Word 文档 → 使用 OMML
+
+## 常见错误
+
+### 错误 1：粘贴后显示为文本
+
+**原因**：粘贴位置不对或格式不对
+
+**解决**：
+1. 确保 MathML 以 `<math` 开头
+2. 使用 Alt 文本方法
+3. 或使用 OMML 接口
+
+### 错误 2：显示为方框
+
+**原因**：Word 无法解析 MathML 结构
+
+**解决**：
+1. 检查是否有 `<semantics>` 包装器（我们已移除）
+2. 使用 OMML 格式
+
+### 错误 3：部分显示不正确
+
+**原因**：某些 LaTeX 命令不支持
+
+**解决**：
+1. 检查 LaTeX 语法
+2. 使用 Word 支持的标准命令
+
+## 最终建议
+
+**最简单的方法**：使用 OMML 格式
+
+```bash
+# 1. 获取 LaTeX
+POST /api/v1/image/ocr
+→ 获取 "latex" 字段
+
+# 2. 转换为 OMML
+POST /api/v1/convert/latex-to-omml
+→ 获取 "omml" 字段
+
+# 3. 使用 python-docx 或 Office.js 插入
+```
+
+这样可以避免所有 MathML 兼容性问题！