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 预览效果

相关推荐
花酒锄作田19 小时前
Postgres - Listen/Notify构建轻量级发布订阅系统
python·postgresql
Thomas.Sir19 小时前
第二章：LlamaIndex 的基本概念
人工智能·python·ai·llama·llamaindex
m0_6948455719 小时前
Dify部署教程：从AI原型到生产系统的一站式方案
服务器·人工智能·python·数据分析·开源
李昊哲小课21 小时前
Python办公自动化教程 - 第7章 综合实战案例 - 企业销售管理系统
开发语言·python·数据分析·excel·数据可视化·openpyxl
不知名的老吴21 小时前
返回None还是空集合？防御式编程的关键细节
开发语言·python
李昊哲小课21 小时前
Python办公自动化教程 - 第5章 图表创建 - 让数据可视化
python·信息可视化·数据分析·数据可视化·openpyxl
chushiyunen21 小时前
python pygame实现贪食蛇
开发语言·python·pygame
Dream of maid21 小时前
Python-基础2(流程控制)
python
Lenyiin1 天前
《Python 修炼全景指南：一》从环境搭建到第一个程序
开发语言·python
涛声依旧393161 天前
Python项目实战：学生信息管理系统
开发语言·python·数据挖掘
热门推荐
01GitHub 镜像站点02OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程03AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南04Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）05VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）06Claude Code 未登录 使用第三方模型07Oh My Codex 快速使用指南08UV安装并设置国内源09【技术干货】Gemma 4 上手深度指南：本地多模态大模型的新基线10Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services