簡介這份資源面向需要批量處理Word文檔的Python學(xué)習(xí)者與辦公自動化從業(yè)者聚焦用python-docx庫把圖片和表格高效寫入.docx文件解決重復(fù)手工排版、逐份生成文檔的痛點(diǎn)適合具備Python基礎(chǔ)、希望提升文檔處理效率的初中級開發(fā)者。壓縮包共12個(gè)文件約367KB包含10個(gè)docx示例文檔、1個(gè)py腳本和1個(gè)jpg圖片docx用于展示批量生成的工資調(diào)整通知效果py腳本承載圖片遍歷與表格填充的核心邏輯jpg則作為插入圖片的素材。目前已有181人學(xué)習(xí)下載。讀者可從中獲得可直接運(yùn)行的批量處理腳本理解Document創(chuàng)建、add_picture插圖、add_table建表與cell填充、doc.save保存等關(guān)鍵用法并借助os庫遍歷目錄的思路把同一套流程遷移到通知、報(bào)表、臺賬等場景快速搭建屬于自己的文檔自動化方案。1. 批量把圖片和表格塞進(jìn) Word一份能直接跑的 python-docx 腳本包手里攢了三十幾份巡檢記錄每份都要把現(xiàn)場照片和檢測數(shù)據(jù)表貼進(jìn)對應(yīng)的 Word 模板里手動復(fù)制粘貼到第三份的時(shí)候我就知道這事不能這么干。這份資源就是沖著這個(gè)場景來的一個(gè)基于 python-docx 的批量寫入腳本包把散落在文件夾里的圖片和表格按規(guī)則灌進(jìn) .docx省掉重復(fù)勞動。它適合兩類人——一類是天天跟報(bào)表、臺賬、檢測記錄打交道的辦公崗另一類是想拿 python-docx 練手但不知道從哪下手的開發(fā)者。核心邏輯不復(fù)雜難的是圖片尺寸、表格樣式、中文字體這些細(xì)節(jié)腳本包里都做了預(yù)設(shè)改幾個(gè)路徑就能跑。2. 拆開腳本包python-docx 寫入圖片和表格的底層邏輯2.1 為什么選 python-docx 而不是直接操作 XMLWord 的 .docx 本質(zhì)是個(gè) zip 包里面是一堆 XML。理論上你可以用 zipfile 解壓、改 document.xml、再壓回去但這條路走一次就不想走第二次——命名空間、關(guān)系映射、rId 分配任何一處對不上Word 打開就報(bào)“內(nèi)容有問題”。python-docx 把這層封裝掉了它把 document.xml 里的段落、表格、圖片關(guān)系都抽象成 Python 對象你調(diào) add_picture、add_table 就行。常見做法是用 python-docx 做主體寫入遇到它不支持的冷門樣式比如某些域代碼、復(fù)雜頁眉再退回 lxml 操作底層 XML。這份腳本包走的就是這個(gè)路線主體用 python-docx個(gè)別地方用 OxmlElement 補(bǔ)了邊框和底紋。選型上還有一個(gè)考慮是依賴輕。python-docx 只依賴 lxml 和 typing-extensionspip 裝完就能用不需要裝 Office也不需要 COM 接口。這意味著它能在 Linux 服務(wù)器上跑也能塞進(jìn)定時(shí)任務(wù)里。如果你之前用 win32com 操作 Word應(yīng)該體會過那種“必須開著 Word 進(jìn)程、偶爾卡死、報(bào)錯(cuò)信息看不懂”的滋味python-docx 在這點(diǎn)上干凈得多。2.2 圖片寫入尺寸、對齊和路徑的三個(gè)參數(shù)先看圖片寫入的核心代碼。腳本包里把這段封裝成了insert_images(doc, img_dir, width_cm12)from docx import Document from docx.shared import Cm from docx.enum.text import WD_ALIGN_PARAGRAPH import os def insert_images(doc, img_dir, width_cm12): 把 img_dir 下的圖片按文件名排序后逐張插入 doc width_cm: 圖片寬度單位厘米高度按比例自動縮放 # 只取常見圖片格式避免把縮略圖緩存也讀進(jìn)來 exts (.png, .jpg, .jpeg, .bmp) files sorted( f for f in os.listdir(img_dir) if f.lower().endswith(exts) ) for fname in files: path os.path.join(img_dir, fname) # 先加一個(gè)空段落再往段落里加圖片方便控制對齊 para doc.add_paragraph() para.alignment WD_ALIGN_PARAGRAPH.CENTER run para.add_run() # 只給寬度高度自動等比縮放避免圖片被拉變形 run.add_picture(path, widthCm(width_cm)) # 圖片下方加一行文件名做標(biāo)注不需要可刪 cap doc.add_paragraph(fname) cap.alignment WD_ALIGN_PARAGRAPH.CENTER邏輯說明add_picture只傳 width 的時(shí)候python-docx 會按圖片原始寬高比自動算高度這是最穩(wěn)的做法。如果你同時(shí)傳 width 和 height圖片會被強(qiáng)行拉伸人像和表格截圖會變形。參數(shù)width_cm默認(rèn) 12 厘米對應(yīng) A4 紙正文寬度約 15.9 厘米留出邊距后的常見值你可以按模板調(diào)整。路徑處理上有個(gè)細(xì)節(jié)os.listdir返回的順序在不同系統(tǒng)上不一致所以腳本里加了sorted。如果你的圖片文件名是img1.jpg、img2.jpg、img10.jpg這種字符串排序會把 img10 排到 img2 前面這時(shí)候需要改成按數(shù)字排序import re files.sort(keylambda x: int(re.search(r\d, x).group()))這個(gè)坑我在第一次批量插巡檢照片的時(shí)候就踩了十張照片順序全亂后來加了自然排序才對上。2.3 表格寫入從列表數(shù)據(jù)到帶樣式的 Word 表格表格寫入比圖片多一層結(jié)構(gòu)。腳本包里insert_table(doc, data, headersNone, styleTable Grid)的實(shí)現(xiàn)def insert_table(doc, data, headersNone, styleTable Grid): data: 二維列表如 [[A, 1], [B, 2]] headers: 表頭列表為 None 時(shí)不生成表頭行 style: Word 內(nèi)置表格樣式名Table Grid 帶全邊框 rows len(data) (1 if headers else 0) cols len(headers) if headers else len(data[0]) table doc.add_table(rowsrows, colscols) table.style style if headers: for j, h in enumerate(headers): cell table.cell(0, j) cell.text str(h) # 表頭加粗 for p in cell.paragraphs: for r in p.runs: r.bold True offset 1 if headers else 0 for i, row in enumerate(data): for j, val in enumerate(row): table.cell(i offset, j).text str(val) return table邏輯說明add_table創(chuàng)建的是空表格行列數(shù)必須提前算好。styleTable Grid是 Word 內(nèi)置樣式名帶全邊框最常用。如果你想要三線表得手動設(shè)邊框python-docx 沒有直接的三線表樣式需要用 OxmlElement 改 tblBorders腳本包里附了這段代碼。參數(shù)上要注意data的每一行長度必須一致否則len(data[0])算出來的列數(shù)會對不上寫入時(shí)索引越界。我一般會在調(diào)用前加一句校驗(yàn)assert len(set(len(r) for r in data)) 1, 每行列數(shù)不一致中文字體是另一個(gè)高頻問題。python-docx 默認(rèn)字體是 Calibri中文會回退到宋體但如果你在模板里指定了字體寫入的表格可能不繼承。穩(wěn)妥做法是顯式設(shè)置from docx.oxml.ns import qn style doc.styles[Normal] style.font.name Times New Roman style.element.rPr.rFonts.set(qn(w:eastAsia), 宋體)這段要放在創(chuàng)建文檔之后、寫入內(nèi)容之前否則已經(jīng)寫入的段落不會更新。2.4 批量循環(huán)一份數(shù)據(jù)對應(yīng)一份文檔的目錄約定腳本包的主入口是batch_generate(template_path, data_root, out_dir)目錄約定是這樣的data_root/ record_001/ images/ # 該記錄的圖片 table.csv # 該記錄的表格數(shù)據(jù) record_002/ ...主循環(huán)代碼import csv from docx import Document def batch_generate(template_path, data_root, out_dir): os.makedirs(out_dir, exist_okTrue) for case in sorted(os.listdir(data_root)): case_dir os.path.join(data_root, case) if not os.path.isdir(case_dir): continue # 每份文檔都從模板復(fù)制一份保留頁眉頁腳和樣式 doc Document(template_path) img_dir os.path.join(case_dir, images) if os.path.isdir(img_dir): insert_images(doc, img_dir) csv_path os.path.join(case_dir, table.csv) if os.path.exists(csv_path): with open(csv_path, encodingutf-8-sig) as f: reader list(csv.reader(f)) insert_table(doc, reader[1:], headersreader[0]) doc.save(os.path.join(out_dir, f{case}.docx))邏輯說明Document(template_path)是打開模板而不是新建空文檔這樣模板里的頁眉、頁腳、樣式、頁面設(shè)置都會保留。encodingutf-8-sig是為了兼容 Excel 導(dǎo)出的 CSV 帶 BOM 頭的情況不加這個(gè)參數(shù)第一列會多一個(gè)不可見字符。參數(shù)out_dir建議和data_root分開避免輸出文件被下一輪循環(huán)當(dāng)成輸入。如果你要覆蓋原文件記得先備份。3. 避坑排查圖片不顯示、表格錯(cuò)位、字體亂掉的五個(gè)血淚經(jīng)驗(yàn)3.1 圖片插入后 Word 顯示紅叉或空白現(xiàn)象腳本跑完沒報(bào)錯(cuò)打開 docx 圖片位置是紅叉或空白框。原因python-docx 插入圖片時(shí)是把圖片二進(jìn)制寫進(jìn) docx 包里的正常不會丟。出現(xiàn)紅叉通常是圖片本身損壞或者擴(kuò)展名和實(shí)際格式不符——比如把 webp 改成 jpg 后綴python-docx 按 jpg 解析失敗但沒拋異常。解決插入前用 PIL 校驗(yàn)一遍from PIL import Image try: Image.open(path).verify() except Exception as e: print(f跳過損壞圖片 {path}: {e}) continue3.2 表格列寬在 Word 里被自動調(diào)整現(xiàn)象腳本里沒設(shè)列寬Word 打開后表格列寬忽寬忽窄跟預(yù)期不符。原因python-docx 創(chuàng)建表格時(shí)如果不設(shè)列寬Word 會按“自動調(diào)整”渲染列寬取決于內(nèi)容長度。table.autofit False只是關(guān)掉自動調(diào)整還需要顯式設(shè)每列寬度。解決創(chuàng)建表格后逐列設(shè)置table.autofit False for j, w in enumerate([Cm(3), Cm(5), Cm(4)]): for cell in table.columns[j].cells: cell.width w注意cell.width要每個(gè)單元格都設(shè)只設(shè)column.width在某些 Word 版本上不生效。3.3 中文字體在表格里變成宋體標(biāo)題字體沒繼承現(xiàn)象正文段落字體正常表格里的中文全變成宋體和模板不一致。原因表格單元格的段落用的是 Normal 樣式但 python-docx 寫入時(shí)沒有顯式指定 eastAsia 字體Word 回退到默認(rèn)中文字體。解決寫入表格后遍歷單元格統(tǒng)一設(shè)字體for row in table.rows: for cell in row.cells: for p in cell.paragraphs: for r in p.runs: r.font.name 微軟雅黑 r.element.rPr.rFonts.set(qn(w:eastAsia), 微軟雅黑)3.4 批量跑完發(fā)現(xiàn)文檔數(shù)量對不上現(xiàn)象data_root 下有 30 個(gè)文件夾out_dir 只生成了 28 個(gè) docx。原因通常是文件夾名排序后中間某個(gè)文件夾里沒有 images 也沒有 table.csv腳本跳過了或者文件夾名含特殊字符導(dǎo)致os.path.join路徑異常。解決在循環(huán)里加日志把跳過的文件夾打出來else: print(f跳過空目錄: {case_dir})另外檢查文件夾名有沒有前后空格Windows 下os.listdir會保留空格os.path.isdir可能判斷失敗。3.5 模板里的頁眉頁腳在輸出文檔里丟了現(xiàn)象模板有頁眉頁腳生成的文檔頁眉頁腳是空的。原因Document(template_path)會保留頁眉頁腳但如果模板的頁眉頁腳是“鏈接到前一節(jié)”且第一節(jié)被修改過可能出現(xiàn)異常。更常見的原因是模板本身是用舊版 Word 保存的python-docx 讀取時(shí) section 信息不完整。解決確認(rèn)模板是 .docx 格式不是 .doc 改后綴用 Word 重新另存為 .docx。如果還不行在腳本里顯式復(fù)制 sectionfrom copy import deepcopy for section in doc.sections: for hf in [section.header, section.footer]: for p in hf.paragraphs: pass # 頁眉頁腳內(nèi)容已在模板中通常不需要額外操作這個(gè)問題的根因多半在模板不在腳本換一個(gè)干凈的 .docx 模板通常就好了。4. 進(jìn)階技巧用配置表驅(qū)動不同模板和字段映射腳本包默認(rèn)是“一個(gè)模板對應(yīng)一種數(shù)據(jù)布局”但實(shí)際辦公場景里經(jīng)常是“同一批數(shù)據(jù)要套不同模板”或者“不同文件夾的表格列順序不一樣”。這時(shí)候硬編碼就不夠了我一般會加一層 YAML 配置# config.yaml templates: - name: inspection template: templates/inspection.docx image_width_cm: 10 table_style: Table Grid column_map: [0, 2, 1] # 把 CSV 的第0/2/1列映射到表格第0/1/2列 - name: summary template: templates/summary.docx image_width_cm: 14 table_style: Light Shading column_map: null # null 表示不重排讀取配置的代碼import yaml def load_config(path): with open(path, encodingutf-8) as f: return yaml.safe_load(f) def apply_column_map(row, mapping): if mapping is None: return row return [row[i] for i in mapping]這樣改模板和列映射不用動 Python 代碼交給辦公崗?fù)赂?YAML 就行。column_map的索引從 0 開始寫的時(shí)候注意 CSV 里有沒有序號列有的話要跳過。另一個(gè)進(jìn)階用法是給圖片加統(tǒng)一水印。python-docx 本身不支持水印但可以在插入圖片前用 PIL 把水印燒進(jìn)圖片from PIL import Image, ImageDraw def add_watermark(src, dst, text內(nèi)部資料): img Image.open(src).convert(RGBA) overlay Image.new(RGBA, img.size, (0, 0, 0, 0)) draw ImageDraw.Draw(overlay) draw.text((10, 10), text, fill(255, 0, 0, 128)) out Image.alpha_composite(img, overlay).convert(RGB) out.save(dst, quality85)這個(gè)操作會重新編碼圖片畫質(zhì)有輕微損失如果原圖是掃描件建議 quality 設(shè) 95 以上。驗(yàn)證方法上我習(xí)慣跑完腳本后隨機(jī)抽三份文檔打開檢查圖片順序、表格邊框、字體三處。批量場景下肉眼全檢不現(xiàn)實(shí)但抽檢能攔住大部分低級錯(cuò)誤。另外可以在腳本末尾加一句統(tǒng)計(jì)print(f生成 {len(os.listdir(out_dir))} 份輸入 {len(os.listdir(data_root))} 份)數(shù)字對不上就回頭查 3.4 那條。從那以后我每次改完腳本都強(qiáng)制先拿兩份樣本數(shù)據(jù)跑一遍確認(rèn)輸出沒問題再上全量。批量操作最怕的就是跑完一百份才發(fā)現(xiàn)模板選錯(cuò)了重跑的時(shí)間成本比驗(yàn)證高得多。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取