269 lines
6.8 KiB
Markdown
269 lines
6.8 KiB
Markdown
# Monaco Editor 差异对比功能使用指南
|
||
|
||
## 📦 安装依赖
|
||
|
||
在项目根目录执行以下命令安装 Monaco Editor：
|
||
|
||
```bash
|
||
npm install monaco-editor @monaco-editor/react
|
||
```
|
||
|
||
### 依赖说明
|
||
|
||
- **monaco-editor**: Monaco Editor 核心包（VS Code 的编辑器组件）
|
||
- **@monaco-editor/react**: Monaco Editor 的 React 封装，提供 React 组件
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 访问演示页面
|
||
|
||
启动项目后，访问：`http://localhost:5173/monaco-demo`
|
||
|
||
### 2. 查看效果
|
||
|
||
页面会展示两份合同的差异对比：
|
||
- **左侧**：原始合同（2024年1月版本）
|
||
- **右侧**：修改后的合同（2024年3月版本）
|
||
|
||
### 3. 使用导航功能
|
||
|
||
- **上一处差异**：跳转到前一个修改位置
|
||
- **下一处差异**：跳转到后一个修改位置
|
||
- **重置示例**：恢复默认的示例文本
|
||
|
||
## 🎨 差异高亮说明
|
||
|
||
| 颜色 | 含义 | 示例 |
|
||
|------|------|------|
|
||
| 🟢 **绿色** | 新增的行 | `+ 第七条 保密条款（新增）` |
|
||
| 🔴 **红色** | 删除的行 | `- 第八条 其他约定` |
|
||
| 🟡 **黄色** | 修改的内容 | `总金额：1,000,000 → 1,500,000` |
|
||
|
||
## 📂 文件结构
|
||
|
||
```
|
||
app/
|
||
├── routes/
|
||
│ └── monaco-demo.tsx # Monaco 演示页面
|
||
└── docs/
|
||
└── monaco-editor-使用指南.md # 本文档
|
||
```
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
### DiffEditor 主要配置项
|
||
|
||
```typescript
|
||
<DiffEditor
|
||
height="100%" // 编辑器高度
|
||
language="plaintext" // 语言模式（plaintext/javascript/json等）
|
||
original={originalText} // 原始文本
|
||
modified={modifiedText} // 修改后的文本
|
||
options={{
|
||
readOnly: true, // 只读模式
|
||
renderSideBySide: true, // 并排显示（false为内联模式）
|
||
ignoreTrimWhitespace: false, // 不忽略空格差异
|
||
fontSize: 14, // 字体大小
|
||
wordWrap: 'on', // 自动换行
|
||
minimap: { enabled: true }, // 显示缩略图
|
||
}}
|
||
/>
|
||
```
|
||
|
||
### 常用选项
|
||
|
||
| 选项 | 说明 | 可选值 |
|
||
|------|------|--------|
|
||
| `readOnly` | 是否只读 | `true` / `false` |
|
||
| `renderSideBySide` | 并排/内联显示 | `true`(并排) / `false`(内联) |
|
||
| `ignoreTrimWhitespace` | 忽略首尾空格 | `true` / `false` |
|
||
| `fontSize` | 字体大小 | 数字，如 `14` |
|
||
| `wordWrap` | 自动换行 | `'on'` / `'off'` / `'wordWrapColumn'` |
|
||
| `theme` | 主题 | `'vs'`(浅色) / `'vs-dark'`(深色) / `'hc-black'`(高对比度) |
|
||
|
||
## 🔧 高级功能
|
||
|
||
### 1. 获取差异信息
|
||
|
||
```typescript
|
||
const handleEditorDidMount = (editor: editor.IStandaloneDiffEditor) => {
|
||
// 获取所有差异
|
||
const lineChanges = editor.getLineChanges();
|
||
console.log('差异数量:', lineChanges?.length);
|
||
console.log('差异详情:', lineChanges);
|
||
};
|
||
```
|
||
|
||
### 2. 跳转到指定差异
|
||
|
||
```typescript
|
||
const goToDiff = (index: number) => {
|
||
const lineChanges = diffEditorRef.current?.getLineChanges();
|
||
if (!lineChanges || index >= lineChanges.length) return;
|
||
|
||
const change = lineChanges[index];
|
||
const modifiedEditor = diffEditorRef.current.getModifiedEditor();
|
||
|
||
// 跳转并高亮
|
||
modifiedEditor.revealLineInCenter(change.modifiedStartLineNumber);
|
||
modifiedEditor.setPosition({
|
||
lineNumber: change.modifiedStartLineNumber,
|
||
column: 1
|
||
});
|
||
};
|
||
```
|
||
|
||
### 3. 切换显示模式
|
||
|
||
```typescript
|
||
// 切换为内联模式
|
||
<DiffEditor
|
||
options={{
|
||
renderSideBySide: false // 内联模式，上下显示
|
||
}}
|
||
/>
|
||
```
|
||
|
||
## 📊 实际应用场景
|
||
|
||
### ✅ 适用场景
|
||
|
||
1. **合同对比**：版本管理、条款变更追踪
|
||
2. **代码审查**：代码变更对比
|
||
3. **文档版本控制**：历史版本对比
|
||
4. **配置文件对比**：JSON、YAML 配置变更
|
||
|
||
### ⚠️ 限制
|
||
|
||
- 只能对比**纯文本**
|
||
- 不支持直接对比 PDF、Word 等格式化文档
|
||
- 需要先提取文本内容
|
||
|
||
## 🔄 扩展：文件上传功能
|
||
|
||
### 未来可以添加的功能
|
||
|
||
1. **上传 PDF 文件** → 提取文本 → 对比
|
||
2. **上传 Word 文件** → 提取文本 → 对比
|
||
3. **导出差异报告** → PDF/Word 格式
|
||
4. **保存对比结果** → 数据库存储
|
||
|
||
### 文本提取示例
|
||
|
||
```typescript
|
||
// PDF 文本提取（需要 pdf-parse 或 pdfjs）
|
||
import * as pdfjsLib from 'pdfjs-dist';
|
||
|
||
async function extractPdfText(file: File): Promise<string> {
|
||
const arrayBuffer = await file.arrayBuffer();
|
||
const pdf = await pdfjsLib.getDocument(arrayBuffer).promise;
|
||
|
||
let text = '';
|
||
for (let i = 1; i <= pdf.numPages; i++) {
|
||
const page = await pdf.getPage(i);
|
||
const content = await page.getTextContent();
|
||
text += content.items.map(item => item.str).join(' ') + '\n';
|
||
}
|
||
|
||
return text;
|
||
}
|
||
|
||
// Word 文本提取（需要 mammoth）
|
||
import mammoth from 'mammoth';
|
||
|
||
async function extractWordText(file: File): Promise<string> {
|
||
const arrayBuffer = await file.arrayBuffer();
|
||
const result = await mammoth.extractRawText({ arrayBuffer });
|
||
return result.value;
|
||
}
|
||
```
|
||
|
||
## 📝 示例代码位置
|
||
|
||
完整代码请查看：`app/routes/monaco-demo.tsx`
|
||
|
||
### 核心代码片段
|
||
|
||
```typescript
|
||
// 1. 引入组件
|
||
import { DiffEditor } from "@monaco-editor/react";
|
||
|
||
// 2. 定义文本
|
||
const originalText = "原始合同内容...";
|
||
const modifiedText = "修改后的合同内容...";
|
||
|
||
// 3. 渲染 Diff Editor
|
||
<DiffEditor
|
||
height="90vh"
|
||
language="plaintext"
|
||
original={originalText}
|
||
modified={modifiedText}
|
||
options={{
|
||
readOnly: true,
|
||
renderSideBySide: true,
|
||
}}
|
||
/>
|
||
```
|
||
|
||
## 🎯 性能优化建议
|
||
|
||
1. **大文件处理**：文本超过 10MB 时，考虑分段加载
|
||
2. **虚拟滚动**：Monaco 自带虚拟滚动，支持大文件
|
||
3. **懒加载**：使用 React.lazy 懒加载 Monaco 组件
|
||
4. **Web Worker**：文本提取放在 Worker 中处理
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q1: Monaco Editor 加载慢？
|
||
|
||
**A**: Monaco Editor 体积较大（~5MB），建议：
|
||
- 使用 CDN 加速
|
||
- 开启 gzip 压缩
|
||
- 使用代码分割
|
||
|
||
### Q2: 中文显示乱码？
|
||
|
||
**A**: 确保文件编码为 UTF-8：
|
||
```typescript
|
||
const text = await file.text(); // 自动识别编码
|
||
```
|
||
|
||
### Q3: 如何自定义主题？
|
||
|
||
**A**: 使用 `defineTheme` 自定义：
|
||
```typescript
|
||
import { editor } from 'monaco-editor';
|
||
|
||
editor.defineTheme('myCustomTheme', {
|
||
base: 'vs',
|
||
inherit: true,
|
||
rules: [{ background: 'EDF9FA' }],
|
||
colors: {
|
||
'editor.foreground': '#000000',
|
||
'editor.background': '#EDF9FA',
|
||
// ... 更多颜色配置
|
||
}
|
||
});
|
||
```
|
||
|
||
## 📚 参考资料
|
||
|
||
- [Monaco Editor 官方文档](https://microsoft.github.io/monaco-editor/)
|
||
- [@monaco-editor/react 文档](https://github.com/suren-atoyan/monaco-react)
|
||
- [VS Code API 文档](https://code.visualstudio.com/api)
|
||
|
||
## 🚧 后续开发计划
|
||
|
||
- [ ] 添加文件上传功能
|
||
- [ ] 支持 PDF 文本提取
|
||
- [ ] 支持 Word 文本提取
|
||
- [ ] 添加差异统计图表
|
||
- [ ] 导出对比报告（PDF/Word）
|
||
- [ ] 保存对比历史记录
|
||
- [ ] 支持多人协同对比
|
||
|
||
---
|
||
|
||
**作者**: 中国烟草AI合同及卷宗审核系统开发团队
|
||
**更新时间**: 2025-01-24
|