PDF中文reportlab排版表格溢出检测PyMuPDF

reportlab 中文 PDF 排版与溢出检测(reportlab-cjk-pdf-layout)

用 reportlab 生成含中文的正式 PDF 并保证排版零溢出

一、这个 skill 是做什么的

当你需要生成中文 PDF(交付资料、技术报告、说明书、BOM / 接线表),或用户反馈 PDF "文字溢出表格 / 多行混杂看不清 / 图内文字重叠"时,用这个 skill。

它覆盖 CJK 字体注册、表格中文自动换行、列宽等比填满、框图 top-down 坐标,以及用 PyMuPDF 做程序化溢出检测的完整闭环——生成后不是靠肉眼"觉得排好了",而是用脚本体检。

它的铁律是:表格单元格必须用 Paragraph 而不能直接传 str(连续中文不会自动断行),并强调生成后必须用程序验证"排好了"。

二、什么时候用它

三、前置条件 / 准备

四、具体用法(步骤)

① 注册中文字体

pdfmetrics.registerFont(UnicodeCIDFont('STSong-Light')),之后 FONT = 'STSong-Light'。段落里 <b>粗体</b>、<br/> 都能用(Paragraph 支持受限 HTML)。

② 写表格:单元格用 Paragraph 包裹

用 grid_table 体系,所有单元格(含表头)都用 Paragraph 包裹 → 中文自动换行、不溢出。列宽用权重等比填满正文宽:CONTENT_W = (210 - 18 - 18) * mm,函数内 scale = CONTENT_W / sum(weights)。

③ 画框图:坐标统一 top-down

reportlab 原生是 bottom-up(y=0 在底部),而人脑是 top-down。全部用"距图顶"坐标,只在一个函数里换算(如 tbox / ty);文字手工拆行,每行不超盒宽。

④ 标准工作流(闭环)

写生成脚本 → python -m py_compile 过语法 → 运行生成 PDF 并打印文件大小 → 跑溢出检测脚本(目标 body overflow = 0)→ 读渲染出的关键页 PNG 肉眼确认无重叠 → 修正循环直至通过 → 清理临时脚本只留正式生成器。

进阶 / 可选:这两步是真正"生成 PDF"和"用程序体检"的命令(需要本地 Python 环境)。它们做的是"把脚本跑成 PDF"和"用 PyMuPDF 检查有没有文字跑到页边距外"。
# 1) 先过语法,再生成 PDF python -m py_compile gen_pdf.py python gen_pdf.py # 2) 程序化溢出检测(目标:body overflow = 0) python check_overflow.py

五、可直接照用的示例

你:这份中文交付资料帮我生成 PDF,但之前生成的表格里的中文都冲到邻列去了,看不清。

AI大模型或AI智能体:那是 reportlab 的老坑——表格直接传字符串时,连续中文不会自动断行,会单行无限延伸冲出边界。我会把所有单元格用 Paragraph 包裹,中文就能自动换行;列宽用权重等比填满,不会越界也不会留大白边。生成完我还会用 PyMuPDF 跑一遍溢出检测,保证 body overflow = 0,再把关键页渲成 PNG 给你肉眼确认无重叠。

你:框图里的文字怎么跑到图外面、还和别的盒子叠一起了?

AI大模型或AI智能体:reportlab 的 Drawing 坐标是 bottom-up(y=0 在底部),和咱们习惯的"距图顶"相反,混用就会把元素放到图外被裁。我统一改成 top-down:所有盒子位置都按"距图顶"算,只在一个换算函数里转成 reportlab 的 y。文字我手工拆好行,标签放到盒子间的空白带,不压标题。生成后照样用脚本体检 + 肉眼复核。

六、常见注意 / 避坑

七、相关 skill / 延伸

← 返回 SKILL 库