TanWenyan/leaudit-platform-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

all in

Browse Source
This commit is contained in:
yorn
2025-12-05 00:09:32 +08:00
parent bb3d22eabf
commit 3d1dbb3f97
214 changed files with 113060 additions and 1232 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/monaco-editor-能力与限制.md
+436
View File
@@ -0,0 +1,436 @@
# Monaco Editor 文档对比能力与限制说明
## 📖 概述
本文档详细说明 Monaco Editor 在比较两份 Word 文档时的能力和限制。Monaco Editor 是 VS Code 的核心编辑器组件，主要用于**纯文本对比**，而非格式化文档对比。
**核心结论**：Monaco Editor 只能识别和对比**纯文本内容**的差异，无法识别字号、字体、颜色、表格结构等格式化信息。
---
## ✅ Monaco Editor **能做什么**
### 1. 纯文本内容对比
- ✅ 逐行对比文字内容的增删改
- ✅ 识别文本的新增、删除、修改
- ✅ 字符级精准差异高亮（行内哪些字符被修改）
- ✅ 区分不同类型的变更（新增、删除、修改）
**示例**：
```diff
- 总金额：人民币壹佰万元整（¥1,000,000.00）
+ 总金额：人民币壹佰伍拾万元整（¥1,500,000.00）
```
### 2. 差异导航功能
- ✅ 跳转到上一处/下一处差异
- ✅ 统计差异数量（显示总共有多少处差异）
- ✅ 自动滚动到差异位置
- ✅ 差异位置高亮显示
- ✅ 显示当前查看的差异序号（如 3/15）
**功能按钮**：
- 「上一处差异」- 跳转到前一个修改位置
- 「下一处差异」- 跳转到后一个修改位置
- 差异计数器 - 显示「发现 X 处差异」
### 3. 差异可视化
#### 并排显示模式（Side-by-Side）
- 左侧：原始文档
- 右侧：修改后的文档
- 差异行用竖线连接
#### 内联显示模式（Inline）
- 上下排列显示差异
- 删除内容在上，新增内容在下
#### 颜色高亮说明
- 🔴 **红色背景**：原始版本的内容（在新版本中被删除或修改前的内容）
- 🟢 **绿色背景**：修改版本的内容（新增或修改后的内容）
- 🟡 **深色高亮**：行内具体修改的字符差异（字符级对比）
### 4. 基本文本操作
- ✅ 搜索功能（Ctrl+F）
- ✅ 自动换行（wordWrap）
- ✅ 行号显示
- ✅ 缩略图导航（Minimap）
- ✅ 鼠标滚轮缩放
- ✅ 只读模式（防止误编辑）
- ✅ 语法高亮（支持多种编程语言）
### 5. 文本提取能力（配合其他库）
项目中集成的文本提取方案：
#### Word 文档提取（使用 mammoth 库）
```typescript
import mammoth from 'mammoth';
async function extractTextFromWord(docUrl: string): Promise<string> {
const response = await fetch(docUrl);
const arrayBuffer = await response.arrayBuffer();
const textResult = await mammoth.extractRawText({ arrayBuffer });
return textResult.value; // 纯文本内容
}
```
**提取结果**：
- ✅ 提取段落文字
- ✅ 提取表格内的文字（但不保留表格结构）
- ✅ 提取列表内容（但不保留序号和缩进）
- ❌ 不提取图片
- ❌ 不提取页眉页脚
#### PDF 文档提取（使用 pdfjs 库）
```typescript
import * as pdfjs from 'pdfjs-dist';
async function extractTextFromPdf(pdfUrl: string): Promise<string> {
const pdf = await pdfjs.getDocument(pdfUrl).promise;
let fullText = '';
for (let i = 1; i <= pdf.numPages; i++) {
const page = await pdf.getPage(i);
const textContent = await page.getTextContent();
const pageText = textContent.items
.map(item => item.str)
.join(' ');
fullText += `\n========== 第 ${i} 页 ==========\n${pageText}\n`;
}
return fullText;
}
```
**提取结果**：
- ✅ 提取文本型 PDF 的文字
- ⚠️ 扫描版 PDF 提取效果差（需要 OCR）
- ❌ 不提取图片和图表
---
## ❌ Monaco Editor **不能做什么**
### 1. 格式识别（完全无法识别）
| 格式类型 | 是否支持 | 说明 |
|---------|---------|------|
| 字号大小 | ❌ | 无法识别 12pt → 14pt 的变化 |
| 字体 | ❌ | 无法识别宋体 → 黑体的变化 |
| 加粗/斜体/下划线 | ❌ | 所有文本样式都会丢失 |
| 字体颜色 | ❌ | 无法识别黑色 → 红色的变化 |
| 背景颜色/高亮 | ❌ | 无法识别文本高亮标记 |
**示例对比**：
**原始 Word 文档**：
> **第一条** 合同双方（加粗、14pt、黑体）
**Monaco 提取后**：
> 第一条 合同双方（纯文本、无格式）
### 2. 排版结构（无法识别）
| 排版元素 | 是否支持 | 说明 |
|---------|---------|------|
| 段落对齐方式 | ❌ | 左对齐/居中/右对齐/两端对齐 |
| 行间距 | ❌ | 1.5倍行距 → 2倍行距的变化 |
| 段前段后间距 | ❌ | 段落间距设置 |
| 首行缩进 | ❌ | 2字符缩进等 |
| 页边距 | ❌ | 上下左右边距 |
| 分页符 | ❌ | 强制分页 |
### 3. 复杂元素（完全丢失）
| 文档元素 | 是否支持 | Monaco 处理方式 |
|---------|---------|----------------|
| 表格 | ❌ | 只提取表格内的文字，单元格结构丢失 |
| 图片 | ❌ | 完全无法显示，跳过 |
| 图表 | ❌ | Excel 图表、SmartArt 等完全丢失 |
| 页眉/页脚 | ❌ | 不提取 |
| 脚注/尾注 | ❌ | 不提取 |
| 批注 | ❌ | Word 批注内容不提取 |
| 修订标记 | ❌ | Word 修订模式的标记丢失 |
**表格示例**：
**原始 Word 表格**：
```
┌────────┬────────┬────────┐
│ 项目 │ 数量 │ 单价 │
├────────┼────────┼────────┤
│ A产品 │ 100 │ 500 │
└────────┴────────┴────────┘
```
**Monaco 提取后**：
```
项目 数量 单价
A产品 100 500
```
### 4. 样式和主题（无法识别）
- ❌ Word 样式表（标题1、标题2、正文等）
- ❌ 主题颜色（Office 主题色）
- ❌ 模板格式
- ❌ 多级列表样式
### 5. 文档元数据（不支持）
- ❌ 作者信息
- ❌ 创建/修改时间
- ❌ 修订历史（谁在何时修改了什么）
- ❌ 文档属性（标题、主题、关键字等）
- ❌ 文档保护/密码
### 6. Office 特有功能（不支持）
| 功能 | 是否支持 | 说明 |
|-----|---------|------|
| 超链接 | ⚠️ 部分支持 | 只显示链接文字，无法点击跳转 |
| 书签 | ❌ | 不支持 |
| 目录 | ⚠️ 部分支持 | 只显示文字，无法点击导航 |
| 交叉引用 | ❌ | 不支持 |
| 域代码 | ❌ | 日期、页码等域代码不计算 |
| 宏/VBA | ❌ | 完全忽略 |
| 嵌入对象 | ❌ | Excel 表格、Visio 图等 |
---
## 📋 功能对比表
### Monaco Editor vs Word 原生比较功能
| 对比维度 | Monaco Editor | Word 原生「比较」 | 备注 |
|---------|--------------|-----------------|------|
| **文本内容** | ✅ 完全支持 | ✅ 完全支持 | Monaco 可精准识别文字差异 |
| **字号大小** | ❌ 不支持 | ✅ 支持 | Word 可显示字号变化 |
| **字体/样式** | ❌ 不支持 | ✅ 支持 | Word 可显示加粗、斜体等 |
| **颜色** | ❌ 不支持 | ✅ 支持 | Word 可显示字体颜色变化 |
| **表格结构** | ❌ 不支持 | ✅ 支持 | Word 可对比表格单元格变化 |
| **图片** | ❌ 不支持 | ✅ 支持 | Word 可显示图片增删 |
| **页眉页脚** | ❌ 不支持 | ✅ 支持 | Word 可对比页眉页脚内容 |
| **批注/修订** | ❌ 不支持 | ✅ 支持 | Word 有完整的修订模式 |
| **并排对比** | ✅ 支持 | ✅ 支持 | 两者都支持左右对比 |
| **差异导航** | ✅ 支持 | ✅ 支持 | 两者都可跳转到差异位置 |
| **在线使用** | ✅ 支持 | ❌ 需要桌面应用 | Monaco 可在浏览器中运行 |
| **跨平台** | ✅ 支持 | ⚠️ 部分支持 | Monaco 支持所有平台，Word 需要安装 |
| **性能** | ✅ 轻量快速 | ⚠️ 依赖 Office | Monaco 加载快，Word 需要完整 Office |
---
## 💡 使用建议
### ✅ 适用场景
1. **纯文本合同对比**
- 只关心条款内容变化
- 不关心格式（字体、字号、颜色）
- 适合法律条款审核
2. **代码文件对比**
- JavaScript、Python、Java 等源代码
- JSON、YAML 配置文件
- Markdown 文档
3. **法律文书文本对比**
- 合同条款修改对比
- 法规文件版本对比
- 协议文本变更追踪
4. **纯文本文档**
- TXT 文件
- CSV 文件
- 日志文件
### ❌ 不适用场景
1. **需要格式审查的文档**
- 投标文件格式审查（需要检查字号、字体）
- 公文格式审核（需要检查页边距、行距）
- 排版质量检查
2. **包含复杂元素的文档**
- 技术文档（包含大量图表）
- 设计方案（包含截图和示意图）
- 财务报表（包含 Excel 表格）
3. **需要保留完整格式的场景**
- 档案归档（需要保留原始格式）
- 打印输出（需要格式一致）
- 格式敏感的文档
---
## 🔄 替代方案
如果您需要对比格式化文档，建议使用以下方案：
### 1. Word 原生功能
**路径**：审阅 → 比较 → 比较文档
**优点**：
- ✅ 完整支持所有 Word 格式
- ✅ 显示详细的修订标记
- ✅ 可选择对比粒度（字符/单词/段落）
**缺点**：
- ❌ 需要安装 Microsoft Word
- ❌ 无法在浏览器中使用
- ❌ 不支持批量对比
### 2. Collabora Online
**说明**：开源的在线 Office 套件，支持 Word 文档预览和编辑
**优点**：
- ✅ 在线使用，无需安装
- ✅ 保留文档格式
- ✅ 支持多人协作
**缺点**：
- ❌ 对比功能不如 Word 原生强大
- ❌ 需要部署 Collabora 服务器
**项目集成参考**：见 `CLAUDE.md` 中的 Collabora 集成文档
### 3. 专业文档对比工具
| 工具名称 | 类型 | 主要功能 |
|---------|------|---------|
| **Beyond Compare** | 桌面应用 | 专业的文件/文件夹对比工具 |
| **WinMerge** | 开源工具 | 免费的文本对比工具 |
| **Araxis Merge** | 商业软件 | 支持 Word/PDF/图片对比 |
| **DiffChecker** | 在线工具 | 简单的在线文本对比 |
---
## 📚 技术实现
### 项目中的实现方式
**文件位置**：`app/routes/monaco-demo.tsx`
**关键步骤**：
1. **提取文本**（使用 mammoth 库）
```typescript
import mammoth from 'mammoth';
const response = await fetch(docUrl);
const arrayBuffer = await response.arrayBuffer();
const textResult = await mammoth.extractRawText({ arrayBuffer });
const plainText = textResult.value;
```
2. **加载到 Monaco Editor**
```typescript
import { DiffEditor } from "@monaco-editor/react";
<DiffEditor
height="90vh"
language="plaintext"
original={originalText} // 原始文档文本
modified={modifiedText} // 修改后的文档文本
options={{
readOnly: true,
renderSideBySide: true, // 并排显示
ignoreTrimWhitespace: false,
fontSize: 14,
wordWrap: 'on',
minimap: { enabled: true },
}}
/>
```
3. **差异导航**
```typescript
const handleEditorDidMount = (editor) => {
const lineChanges = editor.getLineChanges();
console.log(`发现 ${lineChanges.length} 处差异`);
};
const goToNextDiff = () => {
const modifiedEditor = diffEditorRef.current.getModifiedEditor();
modifiedEditor.revealLineInCenter(nextChange.modifiedStartLineNumber);
};
```
### 使用方法
**URL 参数加载文档**：
```
/monaco-demo?doc1=路径1&doc2=路径2
```
**示例**：
```
/monaco-demo?doc1=testWork/合同(1).docx&doc2=testWork/合同(2).docx
```
---
## ⚠️ 注意事项
### 1. 文本提取的限制
- **表格**：表格结构会丢失，只保留单元格内的文字
- **图片**：完全忽略，不提取
- **格式**：所有格式化信息（字体、颜色、大小）全部丢失
### 2. 扫描版 PDF 的问题
- 扫描版 PDF（图片 PDF）几乎无法提取文字
- 需要 OCR（光学字符识别）才能提取文字
- 项目暂不支持 OCR
### 3. 性能考虑
- Monaco Editor 体积较大（约 5MB）
- 建议使用 CDN 加速
- 大文件（>10MB）建议分段加载
### 4. 中文编码问题
- 确保文件编码为 UTF-8
- 使用 `file.text()` 自动识别编码
- 避免使用 GBK 等编码
---
## 📖 相关文档
- [Monaco Editor 使用指南](./monaco-editor-使用指南.md)
- [Monaco Editor 官方文档](https://microsoft.github.io/monaco-editor/)
- [@monaco-editor/react 文档](https://github.com/suren-atoyan/monaco-react)
- [mammoth.js 文档](https://github.com/mwilliamson/mammoth.js)
- [PDF.js 文档](https://mozilla.github.io/pdf.js/)
---
## 🎯 结论
**Monaco Editor 适合用于**：
- ✅ 纯文本内容对比（合同条款、代码、配置文件）
- ✅ 在线文档对比（无需安装桌面软件）
- ✅ 开发者工具集成（代码审查、版本对比）
**Monaco Editor 不适合用于**：
- ❌ 格式敏感的文档对比（投标文件、公文）
- ❌ 包含图表的文档（技术文档、报告）
- ❌ 需要完整保留 Word 格式的场景
**建议**：
- 对于纯文本合同对比，Monaco Editor 是理想选择
- 对于格式敏感的文档，建议使用 Word 原生比较功能
- 对于在线协作场景，可考虑集成 Collabora Online
---
**文档版本**：v1.0
**最后更新**：2025-01-29
**作者**：中国烟草AI合同及卷宗审核系统开发团队