Python 处理 Word 表格时最容易出问题的不是“创建表格”而是“表格样式”。很多同学在 Word 里用鼠标点一下就能套用的自定义样式换到 python-docx 里就会遇到样式名不对、样式不生效、保存后样式丢失等一堆问题。这篇教程就从实际使用角度把“应用自定义样式”和“移除自定义样式”的完整操作逻辑拆开覆盖环境准备、内置样式、自定义样式、批量清理和常见坑排查适合正在用 Python 写文档生成、批量处理报告或做 Word 数据导出的读者。先说一个核心判断如果你只是想把某个表格套上“Table Grid”这种内置样式用table.style Table Grid就够了。难点在于“自定义样式”到底存在哪里、怎么命名、怎么绑定又怎么解除绑定。下面按操作顺序拆成六个部分尽量让每一步都能直接落地。1. 先搞清楚 Word 表格样式的组成和操作入口1.1 Word 样式表和表格样式的关系Word 文档里的样式不是只给文字用的它有一套独立的对象体系。你可以打开一个.docx文件用压缩工具解开看会找到styles.xml。这里面既包含段落样式也包含表格样式。表格样式主要声明了这些信息整个表格的边框类型、颜色、粗细。单元格底纹的默认填充色。表格内文字的字号、字体、颜色。首行、末行、首列、末列是否需要特殊显示。表格内边距和默认段落格式。在 Word 界面里创建一张表格后如果不手动指定样式它会使用文档默认的表格外观而不是“无样式”。很多初学者以为新建表格不需要样式其实 Word 在底层可能已经设置了Normal Table或类似默认样式。用 python-docx 读取时table.style返回的结果会让你知道当前表格绑定了什么。自定义样式本质就是向styles.xml里追加一条w:style w:typetable节点然后让目标表格的w:tbl节点去引用这个样式的styleId。理解了这一点才能真正掌握应用和移除的底层原理。1.2 python-docx 能操作哪些层不能操作哪些层python-docx 是专门处理.docx文档的开源库。它能做的事情包括读取文档中的表格对象。读取表格当前使用的样式名称。给表格设置一个已经存在的样式。在文档样式集合中新增表格样式。修改单元格文字、对齐方式、底纹等。它没有直接提供的接口主要有两个没有专门删除样式对象的高层方法。没有完全兼容 Word 图形界面里那种“应用样式后自动调整所有单元格”的复杂联动。所以这篇文章里凡是涉及深度操作的地方会采用“python-docx 高层接口 _element底层 XML 操作”的组合方式。这种方法虽然多写几行但能解决大量“为什么代码报错”“为什么样式没生效”的问题。实操中我会先把目标.docx复制一份再测试避免原始文件被改坏后无法恢复。这个习惯尤其适合批量处理。2. 环境准备工作依赖、文档结构和最小验证2.1 安装 python-docx先确认当前环境已经装好 python-docx。安装命令很简单pip install python-docx如果你正在做虚拟环境管理不要全局安装先在项目环境里执行上述命令。安装完成后在 Python 交互式环境或脚本里验证一下import docx print(docx.__version__)这里不建议强行固定版本。python-docx 更新并不频繁但不同版本对样式支持细节有差异。如果你的运行版本过旧有些代码可能跑不通优先升级到较新的稳定版本。2.2 准备一个测试用的 Word 文档建议先用 Word 手工建一个包含至少一张表格的test.docx表格内容随便填。如果你手上没有现成文档也可以用 python-docx 直接生成一个测试文档from docx import Document doc Document() table doc.add_table(rows3, cols3) table.style Table Grid table.cell(0, 0).text 商品 table.cell(0, 1).text 数量 table.cell(0, 2).text 备注 table.cell(1, 0).text 键盘 table.cell(1, 1).text 2 table.cell(1, 2).text table.cell(2, 0).text 鼠标 table.cell(2, 1).text 3 table.cell(2, 2).text doc.save(test.docx)这样生成的是带Table Grid样式的表格。注意add_table本身会创建表格对象但如果不指定style默认样式的展示效果在不同 Word 版本里可能不一样。为了测试稳定先用Table Grid作为起点。2.3 先跑一段最小读取代码确认表格存在拿到测试文档后不要直接开始改样式先读取结构from docx import Document doc Document(test.docx) print(段落数量, len(doc.paragraphs)) print(表格数量, len(doc.tables)) for idx, table in enumerate(doc.tables): print(f第 {idx 1} 张表格) print(行数, len(table.rows)) print(列数, len(table.columns)) print(当前样式, table.style) print(样式名, table.style.name)这个步骤能帮你确认几件事文档是否被成功解析。表格数量是否符合预期。表格样式名称是什么。表格对象是否真的是python-docx识别出来的结构。如果这里读取到的表格数量是 0那后面所有样式操作都没有意义。常见原因是目标文档里的不是真正的 Word 表格而是从网页复制来的“假表格”或者被深藏在文本框、图形、内容控件里。处理这种文档前需要先在 Word 或 WPS 中重新转换成真正的表格。3. 在 Word 表格中应用自定义样式从内置到完整自定义3.1 方式一应用内置表格样式先看最简单的情况文档样式集合里已经有可用的表格样式直接绑定。from docx import Document doc Document(test.docx) table doc.tables[0] table.style Table Grid doc.save(test_table_grid.docx)或者传入样式对象style doc.styles[Table Grid] table.style style这里要理解一个坑table.style Table Grid这条语句不是创建新样式而是从当前文档的styles.xml里寻找一个名为Table Grid的样式去绑定。如果某个新建空文档没有这个样式运行时会报错。因此生产项目里不应该硬编码所有内置样式名先判断一下table_grid None for s in doc.styles: if s.name Table Grid: table_grid s break if table_grid is not None: table.style table_grid else: print(当前文档没有 Table Grid 样式)这种做法可以避免因为模板不同导致的“样式不存在”问题。3.2 方式二创建自定义表格样式如果内置样式不满足需求可以新建一个自定义表格样式。from docx import Document from docx.enum.style import WD_STYLE_TYPE from docx.shared import Pt, RGBColor doc Document(test.docx) # 避免重复添加同名样式 style_exists False for s in doc.styles: if s.name 我的自定义表格: style_exists True break if not style_exists: custom_style doc.styles.add_style(我的自定义表格, WD_STYLE_TYPE.TABLE) # 以 Table Grid 为基础样式保留边框 base_style doc.styles[Table Grid] custom_style.base_style base_style # 设置默认字体 custom_style.font.name Microsoft YaHei custom_style.font.size Pt(10) custom_style.font.color.rgb RGBColor(0x40, 0x40, 0x40) # 应用新样式 table doc.tables[0] table.style 我的自定义表格 doc.save(test_custom_style.docx)这段代码里最值得注意的是WD_STYLE_TYPE.TABLE。如果不指定这个类型python-docx 会默认创建段落样式那样你就无法赋值给表格对象。另外base_style不是必须的但建议设置。它的作用是让自定义样式先继承某个已有内置样式的基础外观比如边框、段落格式。否则新样式空无一物Word 打开后可能什么都看不到。有些 python-docx 版本对表格样式字体的支持不如段落样式那么完整如果设置font.name后不起作用不用纠结可以先在样式中固定边框和底纹再对单元格做字体覆盖见 3.4。3.3 给自定义样式补充边框和底纹如果只设置名字和字体样式看起来仍然很单薄。真正常用的是给样式增加边框。python-docx 没有提供类似style.borders这种高层 API所以要操作底层 XMLfrom docx import Document from docx.enum.style import WD_STYLE_TYPE from docx.oxml import OxmlElement from docx.oxml.ns import qn doc Document(test.docx) for s in doc.styles: if s.name 我的自定义表格: custom_style s break else: custom_style doc.styles.add_style(我的自定义表格, WD_STYLE_TYPE.TABLE) base_style doc.styles[Table Grid] custom_style.base_style base_style # 获取样式的 XML 元素 style_element custom_style.element # 找到 tblPr如果不存在则创建 tblPr style_element.find(qn(w:tblPr)) if tblPr is None: tblPr OxmlElement(w:tblPr) style_element.append(tblPr) # 添加边框定义 borders OxmlElement(w:tblBorders) for border_name in (top, left, bottom, right, insideH, insideV): border OxmlElement(fw:{border_name}) border.set(qn(w:val), single) border.set(qn(w:sz), 6) border.set(qn(w:space), 0) border.set(qn(w:color), 4F81BD) borders.append(border) tblPr.append(borders) table doc.tables[0] table.style 我的自定义表格 doc.save(test_custom_border.docx)这段代码的核心逻辑是在样式的w:tblPr里插入w:tblBorders分别定义上、下、左、右、内水平、内垂直六种边框线。如果你希望整个表格只是外框线粗、内线细就不能六条线全部使用同一参数需要分别设置不同的w:sz和w:val。同样的思路可以通过 XML 给某个表格样式添加默认底纹。底纹一般放在w:tblPr里使用w:shd节点shd OxmlElement(w:shd) shd.set(qn(w:val), clear) shd.set(qn(w:color), auto) shd.set(qn(w:fill), DDEBF7) tblPr.append(shd)这会让使用该样式的表格整体带上一层浅蓝色底纹。如果你只想让表头有颜色不建议直接写在这个样式里应该用行或单元格级别的底纹见 3.4。3.4 方式三用单元格局部样式覆盖表格整体很多时候我们说的“应用样式”并不是只改table.style而是希望表头第一行有深色背景、白色加粗文字数据区使用浅色背景或斑马纹。通过 python-docx 对单元格做局部设置可以部分模拟 Word 表格样式中的“首行”“汇总行”效果。from docx import Document from docx.oxml import OxmlElement from docx.oxml.ns import qn from docx.shared import Pt, RGBColor doc Document(test_custom_border.docx) table doc.tables[0] # 给第 0 行的所有单元格设置底纹和字体 for cell in table.rows[0].cells: cell.text cell.text.strip() # 设置底纹 tcPr cell._tc.get_or_add_tcPr() shd OxmlElement(w:shd) shd.set(qn(w:val), clear) shd.set(qn(w:color), auto) shd.set(qn(w:fill), 2E74B5) tcPr.append(shd) # 对单元格内的段落文字设置字体 for paragraph in cell.paragraphs: paragraph.alignment 1 # 居中 for run in paragraph.runs: run.font.bold True run.font.size Pt(10) run.font.color.rgb RGBColor(0xFF, 0xFF, 0xFF) doc.save(test_custom_cell_style.docx)这种做法的优势是快速、直观不需要处理复杂的样式命名和 XML 结构缺点是当你处理十几张表格时代码会重复且很难统一维护。所以实际项目中判断标准很简单只需要统一边框优先做自定义表格样式。需要不同行不同颜色用行标记或单元格底纹覆盖。需要严格复用并保证别人也能在 Word 里直接点选创建真正的自定义表格样式然后绑定。3.5 验证样式是否真正写入文档代码跑完不代表样式一定正常。保存文件后用 Word 打开点一下表格再看表格设计选项卡里显示什么样式。如果显示的是你命名的“我的自定义表格”说明成功。如果打开后发现表格样式没变或者 Word 提示样式名称冲突优先检查两件事样式名是否真的存在于文档styles.xml。表格对象有没有成功绑定到对应样式的styleId。可以通过再次读取验证check_doc Document(test_custom_border.docx) for t in check_doc.tables: print(表格绑定样式, t.style.name)4. 移除 Word 表格中的自定义样式恢复默认和批量清理4.1 正确理解移除样式清除引用还是删除样式定义“移除自定义样式”这句话在不同场景下有不同的含义只想让某张表格不再使用这个自定义样式回到普通表格。想把整个 Word 文档主题里新建出来的样式定义也删除掉。前者只需要操作表格本身后者还需要操作文档样式集合。很多初学者只执行第一种操作就发现 Word 的样式列表里还是有那个“我的自定义表格”于是跑来问“为什么没删除干净”。正常的工作流是先移除表格对样式的引用再删除样式定义。如果样式正被某张表格使用却直接删除定义Word 打开文档时往往会提示“此样式已不存在”或恢复默认严重时还会丢失部分格式。所以不要跳过 4.2 直接做 4.4。4.2 单表移除table.style Nonepython-docx 允许把table.style设置为None。这种写法会把当前表格对w:tblStyle的引用清除掉也就是不再使用任何显式表格样式。from docx import Document doc Document(test_custom_border.docx) table doc.tables[0] table.style None doc.save(test_remove_style_from_table.docx)保存后重新读取会看到表格已经没有可用的表格样式名。Word 打开后表格大概率会使用文档默认的表格样式而不是你自定义的那个。需要注意的是table.style None并不会删除样式名本身也不会把之前应用过的单元格底纹全撤销。因为某些外观效果是你通过“直接修改单元格 XML”覆盖上去的只要没有显式清除那些w:shd节点或字体加粗它们仍然存在。这就告诉我们要区分“样式绑定”和“直接格式”前者可以通过解除引用来移除后者只能逐单元格修改或删除对应节点。4.3 批量移除文档中所有表格的自定义样式批量处理时可以遍历文档里的所有表格from docx import Document doc Document(many_tables.docx) # 先记录哪些表格正在使用自定义表格样式 custom_table_styles [我的自定义表格, 其他自定义样式] removed [] for table in doc.tables: current_name table.style.name if table.style is not None else None if current_name in custom_table_styles: table.style None removed.append(current_name) doc.save(many_tables_removed.docx) print(移除完成涉及样式, removed)这里有一个容易被忽略的问题同一个表格中可能有多个table.style名称但单元格级直接格式不受影响。如果你是要把自己的自定义样式完整移除同时保留边框可以考虑先清掉自定义样式再重新应用内置的Table Grid。这样既不会让表格失去边框也不会残留自定义样式名。table.style None table.style Table Grid这种做法在实际生成报告时非常有用。你可以在处理阶段用自定义样式强调中间状态最终输出前统一换成内置样式。4.4 彻底删除样式定义需要在 styles.xml 中操作如果确认文档中已经没有任何表格引用该自定义样式可以进一步删除样式定义。python-docx 没有提供styles.remove()方法所以需要通过 XML 节点来删除from docx import Document from docx.oxml.ns import qn doc Document(test_custom_border.docx) style_to_delete None for s in doc.styles: if s.name 我的自定义表格: style_to_delete s break if style_to_delete is not None: style_el style_to_delete.element # 先确认样式是否仍被引用这里简单在删除前把文档内表格引用清理掉 for table in doc.tables: if table.style and table.style.name 我的自定义表格: table.style None # 删除样式节点 style_el.getparent().remove(style_el) doc.save(test_style_definition_removed.docx)注意style_to_delete.element拿到的是w:style节点。移除这个节点后该自定义样式就从当前文档移除其他文档并不受影响因为每个docx文件都有独立的样式集合。如果跨目录批量清理多个文件可以写一个函数先遍历所有.docx文件逐个打开逐个检查样式名和表格引用执行移除。真实场景中最好加一个可配置的样式名列表和输出目录不要直接在原文件上改。5. 常见坑排查从样式名到边界设置5.1 找不到样式名或者中文字体、样式名出现异常运行时最常遇到的是KeyError或ValueError提示找不到样式xxx。原因通常是目标文档里的样式名和你代码里的名字不一致或者该样式是从模板里复制的名称带上了副本之类的后缀。排查步骤先打印当前文档的所有表格样式名。确认你要找的样式真实存在。如果找的是中文名尽量确认中文字符编码正常不混入全角空格。可以用这段代码列出所有表格样式from docx import Document from docx.enum.style import WD_STYLE_TYPE doc Document(test.docx) for style in doc.styles: if style.type WD_STYLE_TYPE.TABLE: print(style.name, style.style_id)如果样式名完全相同但代码仍然报错检查是不是你的.docx模板有多个部分而doc.styles只保存了主样式文件中的样式。还有一些样式存放在页眉、页脚或文本框中不会被doc.tables直接发现。5.2 应用了样式但显示不出来代码没有报错table.style.name也正常但 Word 打开之后视觉上没有任何变化。常见原因有三个该样式本身只定义了很少的属性例如没有边框、没有底纹、没有字体颜色。表格中单元格已经存在直接格式直接格式优先于样式定义把样式效果覆盖了。自定义样式没有正确设置base_style导致新样式继承了一个空的默认表格样式。解决方法是先做一个最小验证新建文档新建表格设置样式再只保留样式不添加任何单元格直接格式看 Word 是否变化。如果变化说明不是样式的问题而是你的单元格局部格式覆盖了样式。如果不变检查样式 XML 是否缺少关键节点或者试着把base_style改成Table Grid。另外一个隐蔽原因是“样式主体”与“表格定义”不一致。比如你给一个三段式表格设置了自定义样式但 Word 的表格属性里又启用了“自动调整”导致边框视觉效果被拉长但这不一定是“不显示”只是看起来不对。5.3 Word 里操作正常用 python-docx 解析却不识别这种情况多发生在 WPS 或 Office 365 中创建的文档。某些样式定义可能位于文档的主题文件中或者使用了 python-docx 尚未覆盖的属性。排查逻辑检查w:tblStyle节点是否存在于表格 XML 中。检查styles.xml中对应w:styleId是否存在。如果存在但 python-docx 读取不到很可能是styleId和name不一致。python-docx 的文档对象在绑定样式时通常会根据样式 ID 或名称处理。使用外部工具生成的.docx可能在样式注册上不规范。这时不要死磕高层 API直接用底层 XML 处理from docx import Document from docx.oxml.ns import qn doc Document(weird.docx) for t in doc.tables: tblPr t._tbl.tblPr if tblPr is not None: tblStyle tblPr.find(qn(w:tblStyle)) if tblStyle is not None: print(tblStyle val:, tblStyle.get(qn(w:val)))这样你至少能看到文档底层给表格绑定了什么样式的 ID然后按 ID 去styles.xml里查找。5.4 AI/Markdown 表格导入 Word 后文字不居中是不是样式问题热词里经常提到的“AI 生成的表格在 Word 文档中文字不居中”本质不全是表格样式问题而在于单元格段落默认对齐方式不是 Word 表头常用的居中。Word 表格单元格里的文字是段落。即便你给表格设置了居中如果单元格内部段落没有设置居中文字仍然可能左对齐或两端对齐。正确做法是先遍历单元格内的段落设置paragraph.alignmentfrom docx.enum.text import WD_ALIGN_PARAGRAPH for row in table.rows: for cell in row.cells: for paragraph in cell.paragraphs: paragraph.alignment WD_ALIGN_PARAGRAPH.CENTER同理如果你从 Markdown 复制表格到 Word再通过 Python 处理很可能发现表格缺少统一样式行高不一致列宽自适应也和你预期不一样。这是因为复制产生的 XML 里往往直接写了很多局部属性比如段前段后间距、单元格宽度。你需要在应用预定义样式前先清理这些行内属性否则局部属性会盖住样式。这里有个经验顺序先不看视觉先查看每个单元格段落里是否有大量w:rPr和w:pPr。如果有优先清空或归一化这些局部格式。然后再设置table.style和段落对齐。5.5 批量任务中途卡住或保存文件损坏如果脚本处理几十个文档难免遇到某个文件在读取或保存时崩溃。不要盲目把异常吞掉。建议这样设计循环import traceback from pathlib import Path from docx import Document input_dir Path(input) output_dir Path(output) output_dir.mkdir(exist_okTrue) fail_list [] for file_path in input_dir.glob(*.docx): try: doc Document(str(file_path)) for table in doc.tables: if table.style and table.style.name 我的自定义表格: table.style None out_path output_dir / file_path.name doc.save(str(out_path)) print(成功, file_path.name) except Exception: fail_list.append(file_path.name) traceback.print_exc() print(失败列表, fail_list)使用fail_list而不是直接打印异常是为了后续重跑。很多批处理任务失败不是代码逻辑问题而是某个源文档本身损坏或包含 python-docx 不支持的组件。这时候先跳过记录文件名再单独分析。6. 实战建议何时该用样式何时该直接改单元格写到这里你应该已经能区分三种操作路径只绑定现成样式table.style Table Grid。新建一个表格样式并绑定先在样式集合里添加WD_STYLE_TYPE.TABLE再设置table.style。直接操作单元格局部格式设置字体、底纹、对齐方式。在实际项目中我一般建议的顺序是优先考虑有没有内置样式可以满足如果没有就在文档预处理阶段创建一份自定义表格样式把边框、字体、底纹都在样式层定义好最后才用单元格级覆盖去处理特殊行。为什么这样设计因为样式可以被很多表格复用。你只改一个地方所有绑定该样式的表格都会同步变化。而直接操作单元格格式虽然看起来直观缺点是后续维护成本高只要某一行多一个单元格或换一种底色就要重新遍历一遍代码非常脆弱。移除操作也一样。临时展示可以用table.style None但如果你要长期维护文档模板我更建议把自定义样式保留在模板中只解除表格对它的绑定避免在styles.xml里来回删除导致模板稳定性下降。最后总结一下我自己的操作清单处理前先备份源文件。先读取表格数量、样式名和单元格结构。新建样式的第一步先设置base_style避免空样式。字体、边框、底纹能用样式层解决就不要堆在单元格上。移除样式前先解除引用不要直接删样式节点。批量处理必须记录失败清单。复杂的视觉效果不要指望一步到位先跑一个小样例再用 Word 打开确认。说到底python-docx 只是把你和 Word 的 XML 模型连起来。只要理解样式在styles.xml中如何定义、表格如何用w:tblStyle引用、局部格式如何覆盖样式那么“应用和移除自定义样式”就只是三步找准对象、设置绑定、确认结果。遇到看起来诡异的问题先翻开 XML 看一眼基本都能找到原因。