Python 文件解析： Excel / Word / PDF 的解析、处理、预览与下载

Cxiaomu2026-02-25 9:39

1. 总览：同一个入口，不同解析器

当用户上传文件时，技术链路通常是：

  1. 接收文件并保存原件。
  2. 按扩展名选择对应的 Python 解析函数。
  3. 生成可预览数据。
  4. 前端展示原件与解析结果。
  5. 用户编辑后保存。
  6. 提供原件下载与编辑结果下载。

xlsx
docx
pdf
用户上传文件
Upload API
保存原件
按扩展名路由
Excel 处理器
Word 处理器
PDF 处理器
预览数据
预览数据
预览数据
前端预览与编辑
保存编辑结果
下载原件 / 下载编辑结果

2. 插件与依赖清单

先统一约定：本文里"插件"指第三方依赖包（Python 包 / 前端 npm 包）。

2.1 Python 端插件（后端）

插件 版本（示例） 用途 是否必须
fastapi 0.111.0 提供上传、预览、保存、下载 API 必须
uvicorn 0.29.0 启动 FastAPI 服务 必须
python-multipart 0.0.9 支持 multipart/form-data 文件上传 必须
openpyxl 3.1.2 解析/回写 Excel（xlsx） Excel 必须
pandas 2.2.2 Excel/表格辅助清洗（可选但常用） 推荐
python-docx 1.1.0 解析/生成 Word（docx） Word 必须
pymupdf (fitz) 1.24.9 PDF 文本、表格、分页信息提取 PDF 必须

对应 import 写法（便于直接复制代码）：

  1. from fastapi import FastAPI, UploadFile, File
  2. from openpyxl import load_workbook
  3. from docx import Document
  4. import fitz（来自 pymupdf）

2.2 前端插件（预览与编辑）

插件 版本（示例） 用途 是否必须
xlsx ^0.18.5 浏览器端 Excel 预览（按 sheet 渲染） Excel 预览必须
mammoth ^1.11.0 浏览器端 Word 转 HTML 预览 Word 预览必须
react-data-grid 7.0.0-beta.59 表格编辑组件（Excel/Word 表格/PDF 表格修订） 需要编辑时必须

2.3 可选插件（PDF OCR 兜底）

插件 用途 是否必须
pytesseract + Pillow PDF/图片 OCR 兜底 可选
paddleocr 中文 OCR 兜底（效果通常更好） 可选

2.4 可选插件（兼容旧格式）

插件/工具 用途 是否必须
xlrd 仅当你要直接读取 .xls 时使用 可选
libreoffice (soffice) 把 .doc 转成 .docx，再交给 python-docx 解析 可选

2.5 安装命令示例

bash 复制代码 
# Backend
pip install fastapi uvicorn python-multipart openpyxl pandas python-docx pymupdf

# Frontend
npm install xlsx mammoth react-data-grid

# Optional OCR fallback
pip install pytesseract pillow
# or
pip install paddleocr

# Optional legacy-format support
pip install xlrd

3. 通用基础：上传、存储、路由

3.1 上传接口示例

python 复制代码 
from pathlib import Path
from fastapi import APIRouter, UploadFile, File

router = APIRouter()

@router.post("/api/files/upload")
async def upload(files: list[UploadFile] = File(...)):
    items = []
    for f in files:
        suffix = Path(f.filename).suffix.lower()
        raw_path = save_raw_file(f)  # 保存原件

        if suffix == ".xlsx":
            file_id = process_excel(raw_path)
            file_type = "excel"
        elif suffix == ".docx":
            file_id = process_word(raw_path)
            file_type = "word"
        elif suffix == ".pdf":
            file_id = process_pdf(raw_path)
            file_type = "pdf"
        else:
            items.append({"filename": f.filename, "error": "unsupported file type"})
            continue

        items.append({"file_id": file_id, "type": file_type, "filename": f.filename})

    return {"items": items}

说明：openpyxl 主流场景是 .xlsx，python-docx 主流场景是 .docx。

如果必须支持 .xls / .doc，建议先做"格式转换"再进入本文解析流水线。

3.2 原件下载接口（通用）

python 复制代码 
from fastapi.responses import FileResponse

@router.get("/api/files/{file_id}/download/raw")
def download_raw(file_id: str):
    path = locate_raw_file(file_id)
    return FileResponse(path, filename=path.name)

4. Excel：解析、处理、预览、编辑保存、下载

本章用到的插件：openpyxl、pandas（可选）、xlsx、react-data-grid。

Excel 的特点是天然二维网格，所以处理策略是"保留 sheet + 保留行列"。

4.1 解析（Python）

python 复制代码 
from openpyxl import load_workbook


def parse_excel(path: str) -> dict:
    wb = load_workbook(path, data_only=True)
    sheets: dict[str, list[list[str]]] = {}

    for sheet_name in wb.sheetnames:
        ws = wb[sheet_name]
        rows: list[list[str]] = []
        for row in ws.iter_rows(values_only=True):
            rows.append(["" if c is None else str(c) for c in row])
        sheets[sheet_name] = rows

    return {
        "sheet_names": wb.sheetnames,
        "sheets": sheets,
    }

4.2 处理（可选）

常见的通用处理：

  1. 去掉尾部空行。
  2. 统一行长度（短行补空字符串）。
  3. 把非字符串安全转成字符串，避免前端渲染异常。
python 复制代码 
def normalize_excel_rows(rows: list[list[str]]) -> list[list[str]]:
    if not rows:
        return [[""]]
    width = max(len(r) for r in rows)
    normalized = []
    for r in rows:
        row = ["" if c is None else str(c) for c in r]
        if len(row) < width:
            row += [""] * (width - len(row))
        normalized.append(row[:width])
    return normalized

4.3 前端预览

前端展示方式：

  1. Sheet 名作为 tab。
  2. 当前 sheet 用 table 或 DataGrid 渲染。
  3. 支持切换 sheet。

4.4 编辑保存

http 复制代码 
PUT /api/excel/{file_id}/edit
json 复制代码 
{
  "sheet_name": "Sheet1",
  "rows": [["A1", "B1"], ["A2", "B2"]]
}

后端可把编辑结果保存成：

  1. excel_edits.json（便于二次编辑）。
  2. edited.xlsx（便于下载）。

4.5 下载

  1. 原件：GET /api/excel/{file_id}/download/raw
  2. 编辑版：GET /api/excel/{file_id}/download/edited
python 复制代码 
@router.get("/api/excel/{file_id}/download/edited")
def download_excel_edited(file_id: str):
    edited_path = build_edited_excel(file_id)  # 根据保存的 rows 重建 xlsx
    return FileResponse(edited_path, filename=edited_path.name)

存储 后端 前端 用户 存储 后端 前端 用户 上传 Excel POST /upload 保存 raw.xlsx parse_excel sheet_names + sheets 编辑单元格 PUT /excel/{file_id}/edit 保存 excel_edits.json / edited.xlsx 下载编辑版 GET /excel/{file_id}/download/edited edited.xlsx

5. Word：解析、处理、预览、编辑保存、下载

本章用到的插件：python-docx、mammoth、react-data-grid。

Word 的天然结构是"段落 + 表格"，不建议简单压平为纯二维表。

5.1 解析（Python）

python 复制代码 
from docx import Document


def parse_word(path: str) -> dict:
    doc = Document(path)
    blocks: list[dict] = []

    # 段落块
    for p in doc.paragraphs:
        text = p.text.strip()
        if text:
            blocks.append({"type": "paragraph", "text": text})

    # 表格块
    for table_index, table in enumerate(doc.tables):
        rows = []
        for row in table.rows:
            rows.append([cell.text.strip() for cell in row.cells])
        blocks.append({"type": "table", "table_index": table_index, "rows": rows})

    return {"blocks": blocks}

5.2 处理（可选）

  1. 清理连续空段落。
  2. 表格行列补齐。
  3. 对超长文本做安全截断（仅显示时，不改原文）。

5.3 前端预览

Word 常见做法是双视图：

  1. 原件预览：mammoth 转 HTML，阅读体验更接近原文档。
  2. 编辑视图：
    1. 段落块用文本编辑器。
    2. 表格块用 DataGrid。

5.4 编辑保存

http 复制代码 
PUT /api/word/{file_id}/edit
json 复制代码 
{
  "blocks": [
    {"type": "paragraph", "text": "Updated paragraph"},
    {"type": "table", "table_index": 0, "rows": [["Header1", "Header2"], ["V1", "V2"]]}
  ]
}

后端可以：

  1. 保存 word_edits.json。
  2. 用 python-docx 生成 edited.docx。

5.5 下载

  1. 原件：GET /api/word/{file_id}/download/raw
  2. 编辑版：GET /api/word/{file_id}/download/edited
python 复制代码 
@router.get("/api/word/{file_id}/download/edited")
def download_word_edited(file_id: str):
    edited_docx = build_edited_word_docx(file_id)
    return FileResponse(edited_docx, filename=edited_docx.name)

6. PDF：解析、处理、预览、编辑保存、下载

本章用到的插件：pymupdf（可选 OCR：pytesseract/paddleocr）、react-data-grid。

PDF 的关键是"按页处理"，因为页面是它的天然单位。

6.1 解析（Python）

python 复制代码 
import fitz


def parse_pdf(path: str) -> dict:
    pages = []
    with fitz.open(path) as doc:
        for i in range(doc.page_count):
            page = doc.load_page(i)
            text = page.get_text("text") or ""

            tables = []
            finder = page.find_tables()
            if finder and finder.tables:
                for t in finder.tables:
                    tables.append([[str(c or "").strip() for c in row] for row in t.extract()])

            pages.append({
                "page_no": i + 1,
                "text": text,
                "tables": tables,
                "width": float(page.rect.width),
                "height": float(page.rect.height),
            })

    return {"page_count": len(pages), "pages": pages}

6.2 处理（可选）

  1. 当 find_tables() 抽不到表时，回退到 page.get_text("words") 做词块聚合。
  2. 对文本进行页级摘要（便于快速预览）。
  3. 对识别结果增加 warnings 字段（纯技术提示）。

6.3 前端预览

建议双层：

  1. 原件：iframe/objectURL 直接预览 PDF。
  2. 解析结果：按页展示 text + tables。

6.4 编辑保存

http 复制代码 
PUT /api/pdf/{file_id}/edit
json 复制代码 
{
  "page_no": 1,
  "table_index": 0,
  "rows": [["Col1", "Col2"], ["A", "B"]],
  "notes": "manual correction"
}

后端可保存：

  1. pdf_edits.json
  2. edited.pdf（可选实现：加批注页、嵌入修订信息）

6.5 下载

  1. 原件：GET /api/pdf/{file_id}/download/raw
  2. 编辑版 PDF：GET /api/pdf/{file_id}/download/edited
  3. 编辑记录 JSON（可选）：GET /api/pdf/{file_id}/download/edits-json

存储 后端 前端 用户 存储 后端 前端 用户 上传 PDF POST /upload 保存 raw.pdf parse_pdf（分页提取） pages/meta 修订表格 PUT /pdf/{file_id}/edit 保存 pdf_edits.json / edited.pdf 下载编辑版 GET /pdf/{file_id}/download/edited edited.pdf

7. API 清单（示例）

类型 预览接口 保存接口 下载接口
Excel GET /api/excel/{file_id}/preview PUT /api/excel/{file_id}/edit download/raw / download/edited
Word GET /api/word/{file_id}/preview PUT /api/word/{file_id}/edit download/raw / download/edited
PDF GET /api/pdf/{file_id}/preview PUT /api/pdf/{file_id}/edit download/raw / download/edited

说明：这三组接口可以由同一个服务实现。本文拆开写，仅用于按文件格式独立说明技术实现细节。

8. 工程落地建议（纯技术）

  1. 原件一定要保存，不要只存解析结果。
  2. 编辑结果建议落 JSON，再按需导出编辑版文件。
  3. 下载接口统一加 Content-Disposition: attachment。
  4. 所有预览数据都做空值与类型兜底，前端会省很多判断。
  5. 文件名建议带时间戳，例如：
    1. report_edited_20260224_1530.xlsx
    2. doc_edited_20260224_1530.docx
    3. scan_edited_20260224_1530.pdf

9. 效果

excel预览效果

word预览效果

pdf 预览效果

相关推荐
小羊没烦恼！3 天前
微服务化的基石——持续集成
java·大数据·word·powerpoint·.net
默_笙3 天前
🍙 给每个请求过安检：FastAPI 是怎么把校验写进类型注解的
python
qq_426003963 天前
启动playwright录制codegen生成自动化测试脚本
python·自动化
虎头金猫3 天前
4K 视频总卡在公网带宽？用 N1 + OpenList 把网盘播放链路重新理顺
运维·服务器·网络·python·容器·beautifulsoup·pandas
长沙三为智能科技3 天前
家政小程序开发从0到上线：五阶段交付流程与验收清单
python
伞伞悦读3 天前
【第38期】Python 模块与包详解：import、from、模块搜索路径、包结构和 __init__
开发语言·python
只睡四小时3 天前
Canvas 弹道联机实战：700 行 + 固定时间步长
python·websocket·html5·游戏开发·canvas
奇思妙想聪明勤奋的小羊3 天前
DeepAgents第5章：子Agent 与上下文隔离—让 Agent学会委派
人工智能·python·学习·语言模型
lpfasd1233 天前
2026年第38周GitHub趋势周报
python·科技·github
IZero073 天前
Jev 与 Laya
python·语言模型
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02Telegram APK 下载安装完整指南 — 2026年最新03GitHub 镜像站点04历年考研数学一、数学二、数学三真题试卷及答案PDF05蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接06如何新建文件夹？ 电脑新建文件夹的4种方法072026 爱知・名古屋亚运会怎么看？直播平台+赛程安排分享082026年CSP-J初赛分数线-----预测09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10人工智能（AI）发展史：详细里程碑