# docx_format

**Repository Path**: mmlya/docx_format

## Basic Information

- **Project Name**: docx_format
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-06
- **Last Updated**: 2025-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Word文档内容与格式无损读取与再写入工具

## 项目简介

本项目是一个专业的Word文档处理工具，能够实现对`.docx`文档内容及格式的完整解析与无损还原。支持将Word文档转换为结构化JSON数据，并能从JSON数据完整恢复Word文档。

## 主要功能

### 📖 文档解析功能
- ✅ 支持解析`.docx`格式的Word文档
- ✅ 提取所有段落、标题、表格、图片、页眉页脚等内容
- ✅ 记录详细的格式属性（字体、字号、颜色、对齐方式等）
- ✅ 将图像以base64编码保存，确保完整性
- ✅ **按原始文档顺序解析内容，保持位置关系**

### 🔄 格式转换功能
- ✅ 将Word文档内容转换为结构化JSON数据
- ✅ 保持内容的层级、顺序和嵌套关系
- ✅ 支持从JSON数据完整恢复Word文档
- ✅ 确保格式的无损还原
- ✅ **智能处理文档结构，按原始顺序还原内容**

### 🛠️ 高级特性
- ✅ 详细的日志记录和错误处理
- ✅ 模块化的代码结构，便于维护和扩展
- ✅ 智能的文档结构处理
- ✅ 处理统计信息输出
- ✅ **表格中图像的完整处理**
- ✅ **文本框内容检测和处理**

## 技术架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Word文档      │───▶│   JSON数据      │───▶│   Word文档      │
│   (.docx)       │    │   (结构化)      │    │   (还原)        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
   docx_parser.py         example.json           json_to_word.py
        │                       │                       │
        ▼                       ▼                       ▼
  按序解析文档结构          完整文档结构数据           按序还原文档
```

## 核心技术突破

### 🔥 文档结构按序处理
- **问题解决**：表格和图像还原时不在原来的位置
- **技术方案**：新增`document_structure`字段，记录文档的完整结构顺序
- **效果**：实现了按原始文档顺序的完整还原

### 🔥 表格中图像处理
- **问题解决**：表格中的图像未能处理
- **技术方案**：完善表格解析逻辑，支持单元格中的图像提取
- **效果**：表格单元格中的段落和图像得到完整处理

### 🔥 文本框内容支持
- **问题解决**：Word中的文本框内容未能还原
- **技术方案**：增加文本框检测功能，实现占位符处理
- **效果**：正确识别并标记文本框内容

## 安装要求

```bash
pip install python-docx
```

## 使用方法

### 1. 解析Word文档为JSON

```bash
# 使用默认文件路径
python main.py

# 指定文件路径
python main.py path/to/your/document.docx
```

### 2. 从JSON恢复Word文档

```bash
python json_to_word.py
```

## 文件结构

```
docx_format/
├── docx_parser.py      # Word文档解析器（按序解析）
├── json_to_word.py     # JSON到Word转换器（按序还原）
├── main.py            # 主程序入口
├── input/             # 输入文件目录
│   ├── example.docx   # 示例Word文档
│   └── example.json   # 解析后的JSON数据
├── output/            # 输出文件目录
│   └── example_完整还原.docx  # 恢复的Word文档
├── tasks.md           # 任务清单
└── README.md          # 项目说明
```

## 核心模块说明

### DocxParser (docx_parser.py)
负责解析Word文档的核心类：

```python
class DocxParser:
    def parse_document_structure(self)    # 按序解析文档结构 🔥
    def parse_paragraph_info(self, para)  # 解析段落（含图像）
    def parse_table_info(self, table)     # 解析表格（含图像）🔥
    def parse_textboxes(self)             # 解析文本框 🔥
    def extract_images_from_element(self) # 从元素中提取图像
    def export_to_json(self)              # 导出为JSON
```

### JSON到Word转换器 (json_to_word.py)
负责从JSON恢复Word文档的功能模块：

```python
def process_document_structure(doc, structure)  # 按结构顺序处理 🔥
def process_table_cell(cell, cell_data)        # 处理表格单元格 🔥
def process_textbox(doc, textbox_data)         # 处理文本框 🔥
def add_images_to_paragraph(para, images)     # 向段落添加图像
def process_document_content(doc, data)        # 智能处理文档内容
```

## JSON数据结构

```json
{
  "document_structure": [      // 🔥 新增：按序记录文档结构
    {
      "type": "paragraph",
      "text": "段落文本",
      "images": [...],         // 段落中的图像
      "style": {...}
    },
    {
      "type": "table",
      "rows": [
        [
          {
            "text": "单元格文本",
            "paragraphs": [...], // 🔥 单元格中的段落
            "images": [...]      // 🔥 单元格中的图像
          }
        ]
      ]
    }
  ],
  "textboxes": [               // 🔥 新增：文本框内容
    {
      "type": "textbox",
      "content": [...],
      "images": [...]
    }
  ],
  "paragraphs": [...],
  "headings": [...],
  "tables": [...],
  "images": [...],
  "headers": [...],
  "footers": [...]
}
```

## 处理能力

根据最新测试，本工具能够成功处理：
- ✅ **285个文档结构元素** - 按原始顺序完整处理 🔥
- ✅ **270个段落** - 包含各种格式的文本内容
- ✅ **14个标题** - 多级标题结构
- ✅ **1个表格** - 完整的表格结构和内容，包含单元格图像 🔥
- ✅ **19个图像** - 各种格式的图片（PNG、JPEG等），包含表格中的图像 🔥
- ✅ **1个文本框** - 文本框内容检测和处理 🔥
- ✅ **页眉页脚** - 完整的页眉页脚内容

## 日志输出示例

```
2025-06-06 09:49:30,489 - INFO - 使用文档结构顺序处理内容
2025-06-06 09:49:30,489 - INFO - 按文档结构顺序处理 285 个元素...
2025-06-06 09:49:30,560 - INFO - 成功处理表格: 4行 x 2列
2025-06-06 09:49:30,577 - INFO - 成功按结构顺序处理 285 个元素
2025-06-06 09:49:30,578 - INFO - 成功处理文本框: 1 个内容项, 0 个图像
2025-06-06 09:49:30,600 - INFO - 文档已成功保存为: output/example_完整还原.docx
```

## 特性优势

1. **🔥 位置精确还原** - 通过文档结构按序处理，确保内容在正确位置
2. **🔥 表格图像支持** - 完整处理表格单元格中的图像和段落
3. **🔥 文本框识别** - 自动检测和处理文本框内容
4. **无损转换** - 保持原文档的所有格式和内容
5. **完整支持** - 支持段落、标题、表格、图像、页眉页脚等所有主要元素
6. **智能处理** - 自动处理各种异常情况，确保程序稳定运行
7. **详细日志** - 提供完整的处理过程记录，便于调试和监控
8. **模块化设计** - 代码结构清晰，便于维护和扩展

## 技术栈

- **Python 3.x** - 主要开发语言
- **python-docx** - Word文档处理库
- **base64** - 图像编码处理
- **json** - 数据序列化
- **logging** - 日志记录
- **xpath** - XML元素定位和解析

## 版本更新记录

### v2.0 (2025-06-06) 🔥
- **重大突破**：实现文档结构按序处理
- **新功能**：表格中图像的完整处理
- **新功能**：文本框内容检测和处理
- **优化**：智能文档结构处理逻辑
- **修复**：表格和图像位置不正确的问题

### v1.0 (2025-06-06)
- 基础文档解析和还原功能
- 图像base64编码保存
- 基本的表格和段落处理

## 贡献指南

欢迎提交Issue和Pull Request来改进这个项目！

## 许可证

本项目采用开源许可证，具体请查看LICENSE文件。