320 lines
7.2 KiB
Markdown
320 lines
7.2 KiB
Markdown
# DOCX 解析器使用说明
|
||
|
||
## 简介
|
||
|
||
`docx_parser.py` 是一个功能强大的 DOCX 文件解析工具，支持将 Microsoft Word (.docx) 文档转换为 Markdown 格式。该脚本采用多策略解析机制，按优先级尝试以下解析方法：
|
||
|
||
1. **MarkItDown**（微软官方库）
|
||
2. **python-docx**（成熟的 Python 库）
|
||
3. **XML 原生解析**（备选方案）
|
||
|
||
## 环境要求
|
||
|
||
- Python 3.6+
|
||
- pip
|
||
|
||
## 安装依赖
|
||
|
||
根据你的需求安装相应的解析库：
|
||
|
||
```bash
|
||
# 安装 MarkItDown（推荐）
|
||
pip install markitdown
|
||
|
||
# 安装 python-docx（备选）
|
||
pip install python-docx
|
||
```
|
||
|
||
> 注意：建议至少安装一种解析库。如果未安装任何库，脚本会尝试使用 XML 原生解析，但功能可能受限。
|
||
|
||
## 命令行参数
|
||
|
||
### 基本语法
|
||
|
||
```bash
|
||
python3 docx_parser.py [options] <file_path>
|
||
```
|
||
|
||
### 位置参数
|
||
|
||
| 参数 | 说明 |
|
||
| ----------- | ------------------- |
|
||
| `file_path` | DOCX 文件的绝对路径 |
|
||
|
||
### 选项参数
|
||
|
||
| 参数 | 长参数 | 类型 | 默认值 | 说明 |
|
||
| ---- | ----------- | ---- | ------ | -------------------------------------------------------------- |
|
||
| `-n` | `--context` | 整数 | 2 | 与 `-s` 配合使用，指定每个检索结果包含的前后行数（不包含空行） |
|
||
|
||
### 互斥参数
|
||
|
||
以下参数只能使用其中一个：
|
||
|
||
| 参数 | 长参数 | 说明 |
|
||
| ----- | ----------------- | ----------------------------------------------------- |
|
||
| `-c` | `--count` | 返回解析后的 markdown 文档的总字数 |
|
||
| `-l` | `--lines` | 返回解析后的 markdown 文档的总行数 |
|
||
| `-t` | `--titles` | 返回解析后的 markdown 文档的标题行（1-6级） |
|
||
| `-tc` | `--title-content` | 指定标题名称，输出该标题及其下级内容（不包含#号） |
|
||
| `-s` | `--search` | 使用正则表达式搜索文档，返回所有匹配结果（用---分隔） |
|
||
|
||
## 使用示例
|
||
|
||
### 1. 输出完整 Markdown 内容
|
||
|
||
```bash
|
||
python3 docx_parser.py /path/to/document.docx
|
||
```
|
||
|
||
输出：完整的 Markdown 格式文档内容
|
||
|
||
### 2. 获取文档字数
|
||
|
||
```bash
|
||
python3 docx_parser.py -c /path/to/document.docx
|
||
```
|
||
|
||
输出：文档总字数（数字）
|
||
|
||
### 3. 获取文档行数
|
||
|
||
```bash
|
||
python3 docx_parser.py -l /path/to/document.docx
|
||
```
|
||
|
||
输出：文档总行数（数字）
|
||
|
||
### 4. 提取所有标题
|
||
|
||
```bash
|
||
python3 docx_parser.py -t /path/to/document.docx
|
||
```
|
||
|
||
输出示例：
|
||
|
||
```
|
||
# 主标题
|
||
## 第一章
|
||
### 1.1 简介
|
||
### 1.2 内容
|
||
## 第二章
|
||
```
|
||
|
||
### 5. 提取指定标题内容
|
||
|
||
```bash
|
||
python3 docx_parser.py -tc "第一章" /path/to/document.docx
|
||
```
|
||
|
||
输出：包含所有上级标题的指定章节内容
|
||
|
||
**特点：**
|
||
|
||
- 支持多个同名标题
|
||
- 自动包含完整的上级标题链
|
||
- 包含所有下级内容
|
||
|
||
示例输出：
|
||
|
||
```
|
||
# 主标题
|
||
## 第一章
|
||
这是第一章的内容
|
||
包含所有子章节...
|
||
|
||
### 1.1 简介
|
||
简介内容
|
||
|
||
### 1.2 内容
|
||
详细内容
|
||
```
|
||
|
||
### 6. 搜索关键词
|
||
|
||
#### 6.1 基本搜索
|
||
|
||
```bash
|
||
python3 docx_parser.py -s "关键词" /path/to/document.docx
|
||
```
|
||
|
||
输出：所有匹配关键词的内容片段，默认前后各 2 行上下文，用 `---` 分隔
|
||
|
||
#### 6.2 自定义上下文行数
|
||
|
||
```bash
|
||
# 前后各 5 行
|
||
python3 docx_parser.py -s "关键词" -n 5 /path/to/document.docx
|
||
|
||
# 不包含上下文
|
||
python3 docx_parser.py -s "关键词" -n 0 /path/to/document.docx
|
||
```
|
||
|
||
#### 6.3 正则表达式搜索
|
||
|
||
```bash
|
||
# 搜索包含数字的行
|
||
python3 docx_parser.py -s r"数字\d+" /path/to/document.docx
|
||
|
||
# 搜索邮箱地址
|
||
python3 docx_parser.py -s r"\b[\w.-]+@[\w.-]+\.\w+\b" /path/to/document.docx
|
||
|
||
# 搜索日期格式
|
||
python3 docx_parser.py -s r"\d{4}-\d{2}-\d{2}" /path/to/document.docx
|
||
```
|
||
|
||
输出示例：
|
||
|
||
```
|
||
这是前一行
|
||
包含匹配关键词
|
||
这是后一行
|
||
---
|
||
另一个匹配
|
||
---
|
||
第三个匹配
|
||
```
|
||
|
||
### 7. 将输出保存到文件
|
||
|
||
```bash
|
||
# 保存完整 Markdown
|
||
python3 docx_parser.py /path/to/document.docx > output.md
|
||
|
||
# 保存标题内容
|
||
python3 docx_parser.py -tc "第一章" /path/to/document.docx > chapter1.md
|
||
|
||
# 保存搜索结果
|
||
python3 docx_parser.py -s "关键词" /path/to/document.docx > search_results.md
|
||
```
|
||
|
||
## 功能特性
|
||
|
||
### 多策略解析
|
||
|
||
脚本自动尝试三种解析方法，确保最大的兼容性：
|
||
|
||
1. **MarkItDown**：微软官方库，解析效果最佳
|
||
2. **python-docx**：功能完善的第三方库
|
||
3. **XML 原生解析**：不依赖任何库的备选方案
|
||
|
||
### 智能匹配
|
||
|
||
#### 标题提取
|
||
|
||
- 支持 1-6 级标题识别
|
||
- 自动处理不同样式的标题（Title、Heading 1-6）
|
||
- 保留原始标题层级关系
|
||
|
||
#### 标题内容提取
|
||
|
||
- 支持同名标题提取
|
||
- 自动构建完整上级标题链
|
||
- 包含所有下级内容
|
||
- 保持文档结构完整
|
||
|
||
#### 搜索功能
|
||
|
||
- 支持正则表达式
|
||
- 智能合并相近匹配
|
||
- 上下文行数控制（不包含空行）
|
||
- 结果用 `---` 清晰分隔
|
||
|
||
### 文档处理
|
||
|
||
- 自动移除 Markdown 图片
|
||
- 规范化空白行（连续多个空行合并为一个）
|
||
- 支持表格、列表、粗体、斜体、下划线等格式
|
||
|
||
### 错误处理
|
||
|
||
- 文件存在性检查
|
||
- DOCX 格式验证
|
||
- 解析失败时自动尝试下一种方法
|
||
- 详细的错误提示信息
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何处理大文档？
|
||
|
||
A: 对于非常大的文档，建议：
|
||
|
||
1. 使用 `-tc` 参数只提取需要的章节
|
||
2. 使用 `-s` 参数搜索特定内容
|
||
3. 将输出重定向到文件进行处理
|
||
|
||
### Q: 搜索功能支持哪些正则表达式？
|
||
|
||
A: 支持所有 Python 标准正则表达式语法。需要注意特殊字符的转义：
|
||
|
||
```bash
|
||
# 错误：括号需要转义
|
||
python3 docx_parser.py -s "(关键词)" /path/to/document.docx
|
||
|
||
# 正确
|
||
python3 docx_parser.py -s "\(关键词\)" /path/to/document.docx
|
||
```
|
||
|
||
### Q: 如何获取更多上下文？
|
||
|
||
A: 使用 `-n` 参数调整上下文行数：
|
||
|
||
```bash
|
||
# 默认 2 行（推荐）
|
||
python3 docx_parser.py -s "关键词" /path/to/document.docx
|
||
|
||
# 更多上下文（5 行）
|
||
python3 docx_parser.py -s "关键词" -n 5 /path/to/document.docx
|
||
|
||
# 不包含上下文
|
||
python3 docx_parser.py -s "关键词" -n 0 /path/to/document.docx
|
||
```
|
||
|
||
### Q: 多个同名标题如何处理？
|
||
|
||
A: `-tc` 参数会返回所有同名标题，每个标题都包含其完整的上级标题链：
|
||
|
||
```markdown
|
||
# 主标题
|
||
|
||
## 同名标题 1
|
||
|
||
内容1
|
||
|
||
# 主标题
|
||
|
||
## 同名标题 2
|
||
|
||
内容2
|
||
```
|
||
|
||
## 技术细节
|
||
|
||
### 标题识别规则
|
||
|
||
| 样式名称 | Markdown 标题级别 |
|
||
| --------- | ----------------- |
|
||
| Title | # |
|
||
| Heading 1 | # |
|
||
| Heading 2 | ## |
|
||
| Heading 3 | ### |
|
||
| Heading 4 | #### |
|
||
| Heading 5 | ##### |
|
||
| Heading 6 | ###### |
|
||
|
||
### 列表识别规则
|
||
|
||
| 样式名称 | Markdown 列表格式 |
|
||
| -------------------- | ----------------- |
|
||
| List Bullet / Bullet | - (无序列表) |
|
||
| List Number / Number | 1. (有序列表) |
|
||
|
||
### 文本格式支持
|
||
|
||
| 格式 | 转换结果 |
|
||
| ------ | ----------------- |
|
||
| 粗体 | `**文本**` |
|
||
| 斜体 | `*文本*` |
|
||
| 下划线 | `<u>文本</u>` |
|
||
| 表格 | Markdown 表格格式 |
|