后端【免费下载链接】python-docxCreate and modify Word documents with Python项目地址https://gitcode.com/gh_mirrors/py/python-docx点击查看免费下载在 python-docx 中表格内的所有内容最终都位于单元格中单元格自身的尺寸、外观以及内容的排版方式则由一组独立的属性控制。本文基于仓库中 docs/dev/analysis/features/table/table-cell.rst 这一功能分析文档结合 src/docx/table.py、src/docx/enum/table.py 与 src/docx/oxml/table.py 的源码实现系统讲解 python-docx 中_Cell对象的访问方式、vertical_alignment候选协议、WD_ALIGN_VERTICAL枚举语义、宽度读写、文本与嵌套表格操作以及单元格合并与 WordprocessingML 底层 Schema。读完本文你将能熟练地定位表格中的任意单元格、设置垂直对齐、调整宽度、合并单元格并理解这些操作在w:tcXML 层面的真实映射。一、什么是 Table Cell一切表格内容的容器原分析文档开宗明义表格中的所有内容All content in a table都包含在单元格cell中同时一个单元格还拥有若干影响其尺寸、外观以及内部内容格式化方式的属性。在 python-docx 中这个“单元格”正是_Cell类其类注释为 “Table cell”代理的是 WordprocessingML 的w:tc元素见 src/docx/table.py 中class _Cell(BlockItemContainer)。_Cell继承自BlockItemContainersrc/docx/blkcntnr.py后者为“可以包含块级元素”的容器提供了公共能力包括add_paragraph()、add_table()、paragraphs、tables与iter_inner_content()。也就是说一个单元格和文档正文、页眉页脚一样都是一个块级内容容器既可以容纳段落也可以继续容纳嵌套表格——这对应了 Word 表格的递归特性。从 MS API 的“Partial Summary”部分摘要可以看出Word 原生对象模型赋予单元格的能力包括合并Merge、拆分Split、边框Borders、四周内边距Bottom/Left/Right/TopPadding、列定位Column / ColumnIndex、自动缩排文字FitText、高度Height / HeightRule、首选宽度Preferred Width、行定位Row / RowIndex、底纹Shading、嵌套表格Tables、垂直对齐VerticalAlignment、宽度Width以及自动换行WordWrap。python-docx 目前已经落地了其中与“垂直对齐”“宽度”“合并”“文本访问”等直接相关的部分本文以下各节逐一展开。二、访问单元格三种入口与布局网格寻址要操作单元格第一步是拿到_Cell对象。根据仓库中 docs/dev/analysis/features/table/cell-merge.rst 的归纳有三种方式Table.cell(row_idx, col_idx)按 (行, 列) 索引定位(0, 0)是左上角单元格源码见 src/docx/table.py 中Table.cell()其通过cell_idx col_idx (row_idx * self._column_count)在_cells序列中取元素Row.cells[col_idx]从某行的cells元组中按下标取Column.cells[col_idx]从某列的cells元组中按下标取。三者定位的是同一个底层w:tc元素因此得到的_Cell对象彼此相等python-docx 中代理对象的相等性定义为“是否指向同一个 XML 元素”见 src/docx/shared.py 中ElementProxy.__eq__ table document.add_table(3, 3) middle_cell table.cell(1, 1) table.rows[1].cells[1] middle_cell True table.columns[1].cells[1] middle_cell True需要强调的是单元格是按布局网格layout grid位置寻址的合并产生的跨行/跨列 span 会“占用”多个网格地址落在 span 内的任意地址都返回该 span 的最左上角单元格。因此len(Row.cells)永远等于网格列数、len(Column.cells)永远等于表格行数与是否存在合并单元格无关这一点在Table._cells的实现中体现每个w:tc按其grid_span重复追加引用vMergecontinue时则复用上一行同列单元格见 src/docx/table.py。三、候选协议Cell.vertical_alignment 垂直对齐原文档给出的是vertical_alignment的“候选协议”Candidate protocol这也是 python-docx 实际落地的公开 API 之一。其使用方式为从docx.enum.table导入WD_CELL_ALIGN_VERTICAL更常用的别名是WD_ALIGN_VERTICAL from docx.enum.table import WD_CELL_ALIGN_VERTICAL cell table.add_row().cells[0] cell docx.table._Cell object at 0x... cell.vertical_alignment None cell.vertical_alignment WD_CELL_ALIGN_VERTICAL.CENTER print(cell.vertical_alignment) CENTER (1)值得注意的细节未设置时读取返回None表示垂直对齐“继承自样式层级”inherited源码中_Cell.vertical_alignment的 getter 在tcPr不存在或w:vAlign子元素缺失时返回Nonesrc/docx/table.py**赋值为None是“删除显式设置、恢复继承”**的手段setter 走get_or_add_tcPr()后把vAlign_val设为None最终在 src/docx/oxml/table.py 的CT_TcPr.vAlign_valsetter 中触发_remove_vAlign()删除整个w:vAlign元素打印枚举显示名称和数值如CENTER (1)这是因为WD_CELL_VERTICAL_ALIGNMENT继承自BaseXmlEnumsrc/docx/enum/base.py其成员同时携带 Python 名称、XML 字面值top/center/bottom/both和 MS API 整数值。该行为在单元测试中有完整覆盖tests/test_table.py的Describe_Cell.it_knows_its_vertical_alignment与it_can_change_its_vertical_alignment通过参数化用例验证了“读取w:vAlign{w:valbottom}得到WD_ALIGN_VERTICAL.BOTTOM”“写入CENTER生成w:vAlign w:valcenter/”“写入None移除w:vAlign”等全部读写路径。四、WD_ALIGN_VERTICAL 枚举四个取值与各自语义原文档完整列出了WD_ALIGN_VERTICAL枚举MS API 名为WdCellVerticalAlignment的全部成员及其 OpenXml 字面值python-docx 在 src/docx/enum/table.py 中逐一定义枚举成员数值OpenXml 字面值语义TOP0top文本对齐到单元格顶部边框CENTER1center文本对齐到单元格垂直居中BOTTOM3bottom文本对齐到单元格底部边框BOTH101bothOpenXml 规范中存在、但 Word 本身不提供该选项需要特别向读者说明的是BOTH对应原文档的wdAlignVerticalBoth它是 OpenXml 规范ST_VerticalJc允许both值里的合法值但Word 界面上并不存在这一选项其实际渲染行为不明确原文档明确建议“最好避免使用”“probably best to avoid this option”。仓库源码的 docstring 也原样保留了这个提醒见 src/docx/enum/table.py 中BOTH成员注释。因此在实操中请只使用TOP/CENTER/BOTTOM。从源码结构看WD_ALIGN_VERTICAL是WD_CELL_VERTICAL_ALIGNMENT的别名WD_ALIGN_VERTICAL WD_CELL_VERTICAL_ALIGNMENT两者均可从docx.enum.table导入vertical_alignment属性接受的赋值类型即WD_CELL_VERTICAL_ALIGNMENT | None见 src/docx/table.py 中vertical_alignmentsetter 的类型标注。五、Specimen XML垂直对齐在文档里的真实模样原文档提供了一段“Specimen XML”样例 XML展示了带垂直对齐设置的单元格在解压后的word/document.xml中长什么样w:tc w:tcPr w:tcW w:w7038 w:typedxa/ w:vAlign w:valbottom/ /w:tcPr w:p w:pPr w:pStyle w:valListBullet/ /w:pPr w:r w:tAmy earned her BA in American Studies/w:t /w:r /w:p /w:tc对照源码可以读懂这段 XML 的每个组成部分w:tcPr单元格属性容器CT_TcPr类src/docx/oxml/table.py以固定顺序维护tcW、gridSpan、vMerge、vAlign等子元素w:tcW w:w7038 w:typedxa/单元格宽度。w:typedxa表示以 twips缇1/20 磅计CT_TblWidth.widthgetter 仅在type dxa时把它换算为LengthEMU返回其他类型pct/nil/auto返回Nonew:vAlign w:valbottom/垂直对齐对应CT_VerticalJc类w:val为必填属性取值受WD_CELL_VERTICAL_ALIGNMENT枚举约束w:p与后续段落/文本单元格的块级内容WML 要求每个单元格至少含一个块级元素、且以段落结尾。python-docx 新建表格时CT_Tbl.new_tbl()/_tcs_xml()见 src/docx/oxml/table.py会为每个单元格生成w:tcPrw:tcW w:typedxa w:w...//w:tcPr加一个空w:p/这与上述结构完全一致——这也解释了为什么读取cell.width通常能拿到数值而vertical_alignment默认是None新建单元格不带w:vAlign。六、Schema 深度解读CT_Tc / CT_TcPr / 宽度与测量单位原文档从 ISO/IEC 29500OOXMLSchema 层面给出了单元格的完整定义这里逐条对照源码讲解其现实意义。6.1 CT_Tc单元格的骨架CT_Tc是w:tc的类型定义。结构上它包含一个可选的w:tcPr单元格属性与至少一个、可无限重复的块级内容元素w:p、w:tbl、customXml、sdt、修订标记、书签、oMath等经xsd:choice minOccurs1 maxOccursunbounded表达。在 python-docx 中CT_Tc类src/docx/oxml/table.py通过ZeroOrOne(w:tcPr)、OneOrMore(w:p)、OneOrMore(w:tbl)约束子元素并实现了grid_span、vMerge、width、merge()、_grow_to()等核心行为。6.2 CT_TcPr单元格属性仓库CT_TcPr定义了单元格属性元素的有序序列原文档 Schema 列出按文档顺序cnfStyle、tcW、gridSpan、hMerge、vMerge、tcBorders、shd、noWrap、tcMar、textDirection、tcFitText、vAlign、hideMark、headers、修订追踪元素cellIns/cellDel/cellMerge以及tcPrChange。python-docx 的CT_TcPr用_tag_seq与各ZeroOrOne(..., successors...)精确复刻了这一顺序约束保证元素按 Schema 规定插入文档始终合法。6.3 CT_TblWidth 与测量单位CT_TblWidth用于w:tblW、w:tcW等宽度元素含两个必填属性w类型为ST_MeasurementOrPercenttype类型为ST_TblWidth枚举值nil/pct/dxa/auto。对应的简单类型在 python-docx 中实现于 src/docx/oxml/simpletypes.pyST_TblWidth校验取值只能为auto、dxa、nil、pctsrc/docx/oxml/simpletypes.pyST_TwipsMeasure/ST_UniversalMeasure负责把字符串长度换算为 EMUdxa值乘以 635 EMU1 twip 635 EMU同时支持mm/cm/in/pt/pc等通用度量ST_UniversalMeasure的正则模式为-?[0-9](\.[0-9])?(mm|cm|in|pt|pc|pi)ST_MeasurementOrPercent是ST_DecimalNumberOrPercent与ST_UniversalMeasure的联合其中百分比形式形如-?[0-9](\.[0-9])?%。实操上python-docx 的cell.width只把dxa类型的宽度返回为LengthEMUpct百分比宽度会读成None见CT_TblWidth.width与tests/test_table.py中it_knows_its_width_in_EMU对w:w25%返回None的断言。给cell.width赋值时则固定写为w:typedxa并把 EMU 值换算成 twips 落盘。6.4 CT_VerticalJc 与 ST_VerticalJcCT_VerticalJc是w:vAlign的类型仅含一个必填属性val类型为ST_VerticalJc枚举top/center/both/bottom。这正是第四节枚举表在 Schema 层面的来源WD_CELL_VERTICAL_ALIGNMENT的四个成员的 XML 字面值与之逐一对应。源码中CT_VerticalJc.val直接以WD_CELL_VERTICAL_ALIGNMENT为属性类型src/docx/oxml/table.py 的CT_VerticalJc类实现了枚举 ↔ XML 的自动双向转换。七、单元格属性全景宽度、文本与内容容器除了垂直对齐原文档“MS API - Partial Summary”中还点到了多个单元格维度python-docx 已实现的部分集中在_Cell上逐一说明如下。7.1 宽度 width cell.width # 未显式设置时返回 None None cell.width Inches(1.5) cell.width 1371600 # 1.5 inch 1371600 EMU读取_Cell.width委托self._tc.width底层解析w:tcPr/w:tcW写入同样委托CT_Tc.widthsetter强制w:typedxa并把Inches(1.5)EMU换算为 twips见 src/docx/oxml/table.py 的CT_TblWidth.width单位体系python-docx 内部一切长度以EMUEnglish Metric Unit表示Inches/Cm/Mm/Pt/Twips都是Lengthint 子类的便捷构造器换算常数定义在 src/docx/shared.py914,400 EMU 1 英寸36,000 EMU 1 毫米1 twip 635 EMU。7.2 文本 text_Cell.text提供单元格全文的读写 cell.text Amy earned her BA in American Studies cell.text 新内容读取把单元格内所有段落的text用\n连接src/docx/table.py 的_Cell.textgetter写入先tc.clear_content()清空全部内容保留w:tcPr再追加一个含单个 run 的w:prun 内为赋值文本同文件的 setter。注意 setter 是“整体替换”会丢弃单元格原有的一切内容和修订痕迹。7.3 段落与嵌套表格paragraphs / tables / add_paragraph / add_table_Cell继承自BlockItemContainer因而具备完整的块级容器能力 cell.paragraphs # 单元格内的段落列表只读 [docx.text.paragraph.Paragraph object at ...] cell.tables # 单元格内嵌套的表格列表只读 [] p cell.add_paragraph(一段文字, styleListBullet) t cell.add_table(rows2, cols2)paragraphs/tables分别返回单元格内的段落与嵌套表格见 src/docx/blkcntnr.py 的paragraphs/tables属性tests/test_table.py的it_provides_access_to_the_paragraphs_it_contains与it_provides_access_to_the_tables_it_contains对其做了长度、可迭代、可下标访问的断言add_paragraph(text, style)在单元格内容末尾追加段落text可含制表符转为w:tab与换行符转为w:br等转义_Cell.add_paragraphdocstringadd_table(rows, cols)在单元格内追加嵌套表格并自动在表格后补一个空段落因为 Word 要求每个单元格的最后一个元素必须是段落见_Cell.add_table的实现与注释src/docx/table.py。7.4 合并单元格merge / grid_span单元格合并是表格排版中最高频的高级操作对应原文档 MS API 的Merge() a, b row.cells[:2] A a.merge(b) # 用两个对角单元格指定矩形区域 A.grid_span # 水平跨越的网格列数 2grid_span只读属性返回单元格水平跨越的布局网格列数普通单元格为 1见_Cell.grid_span与 tests/test_table.py 的参数化断言 1/2/4merge(other_cell)以本单元格与other_cell为对角构造矩形区域进行合并返回合并后左上角的新_Cellsrc/docx/table.py 的_Cell.merge底层由CT_Tc.merge()→_span_dimensions()→_grow_to()完成先校验区域为矩形非矩形抛出InvalidSpanError异常类定义于 src/docx/exceptions.py再水平吞并右侧w:tc内容拼接、宽度累加、gridSpan增大、删除被吞并元素最后纵向生成vMergerestart/vMergecontinue的延续单元格合并后的内容行为多个源单元格的文本按“原单元格文本 段落标记”顺序拼接空单元格跳过等价于\n.join(cell.text for cell in original_cells if cell.text)原文档Cell content behavior on merge一节。关于纵向合并的 XML 语义原文档XML Semantics一节有精辟总结此处与 src/docx/oxml/simpletypes.py 的ST_Merge取值continue/restart对照说明水平合并只保留最左单元格、其余删除纵向合并时最上方单元格设w:vMerge w:valrestart下方各延续单元格带w:vMerge值为continue且是缺省值见 src/docx/oxml/table.py 中CT_VMerge.val的defaultST_Merge.CONTINUE一旦某行w:tcPr缺失w:vMerge则纵向合并终止。若表格各列布局统一纵向合并甚至只保留顶部单元格并删除其余行。八、从源码到测试行为验证链路为了印证上文全部行为仓库提供了两层验证单元测试tests/test_table.py 的Describe_Cell类完整覆盖grid_span、text读写、vertical_alignment读写、含None继承语义、widthEMU 换算、pct返回None、paragraphs、tables、add_paragraph、add_table、merge等全部_Cell行为Behave 验收测试features/tbl-cell-props.feature 以场景表形式验证“获取/设置_Cell.vertical_alignment”“获取/设置单元格宽度”等属性操作其步骤实现见 features/steps/table.pyfeatures/tbl-cell-access.feature 则用only uniform cells/a horizontal span/a vertical span/a combined span四类 3×3 表格验证行、列、按索引三种访问方式在存在合并 span 时仍返回符合“布局网格”语义的单元格序列。例如tbl-cell-props.feature中的垂直对齐用例Scenario Outline: Set Cell.vertical_alignment Given a _Cell object with state vertical alignment as cell When I assign value to cell.vertical_alignment Then cell.vertical_alignment is value Examples: Cell.vertical_alignment assignment cases | state | value | | inherited | WD_ALIGN_VERTICAL.BOTTOM | | bottom | WD_ALIGN_VERTICAL.CENTER | | center | None | | inherited | None |其中“center → None”与“inherited → None”两条用例正是对“赋None即清除显式设置、恢复继承”这一语义的行为级回归。九、实战速览一段完整的单元格操作示例把本文内容串起来一个典型的 python-docx 表格单元格操作脚本如下可直接复制运行from docx import Document from docx.enum.table import WD_ALIGN_VERTICAL from docx.shared import Inches document Document() table document.add_table(rows3, cols3) # 1. 三种方式访问同一个单元格 cell table.cell(1, 1) assert table.rows[1].cells[1] cell assert table.columns[1].cells[1] cell # 2. 垂直对齐TOP / CENTER / BOTTOMNone 表示继承 cell.vertical_alignment WD_ALIGN_VERTICAL.CENTER print(cell.vertical_alignment) # CENTER (1) cell.vertical_alignment None # 清除显式设置恢复继承 # 3. 宽度EMUInches 便捷构造器 cell.width Inches(1.5) # 4. 文本与块级内容 cell.text 第一行\n第二行 # 整体替换\n 转为换行 p cell.add_paragraph(追加一段, styleNone) # 5. 合并单元格对角定位矩形区域 A table.cell(0, 0).merge(table.cell(0, 1)) A.grid_span # 2 document.save(cell-demo.docx)十、小结回到原分析文档的核心论断表格中的所有内容都住在单元格里而单元格自身的属性决定其尺寸、外观与内容格式。围绕这一论断本文完成了三层递进API 层_Cell的访问入口Table.cell/Row.cells/Column.cells、vertical_alignment、width、text、paragraphs/tables、merge与grid_span枚举层WD_ALIGN_VERTICAL的四个取值0/1/3/101与各自的 OpenXml 字面值和 Word 实际语义特别是BOTH的“规范合法但 Word 不可用”警告XML/Schema 层w:tc/w:tcPr/w:tcW/w:vAlign的结构、ST_TblWidth的dxa/pct/nil/auto四种宽度类型、twips↔EMU 的换算关系以及ST_VerticalJc与枚举的一一映射。如需继续深入可进一步阅读仓库中的关联材料docs/user/tables.rst表格概念uniform table、layout grid、omitted cells、docs/dev/analysis/features/table/cell-merge.rst合并的完整算法与 XML 语义、docs/dev/analysis/features/table/table-row.rst 与 docs/dev/analysis/features/table/table-props.rst行属性与表格属性以及 docs/api/table.rstTable/_Cell/_Row/_Column的 API 索引。赞分享后端【免费下载链接】python-docxCreate and modify Word documents with Python项目地址https://gitcode.com/gh_mirrors/py/python-docx点击查看免费下载相关推荐python-docx 单元格垂直对齐WD_ALIGN_VERTICAL 枚举完全指南python docx 单元格垂直对齐WD_ALIGN_VERTICAL 枚举完全指南 WD_ALIGN_VERTICAL 即 WD_CELL_VERTIC后端鸣潮自动化助手让游戏回归乐趣的智能解决方案鸣潮自动化助手让游戏回归乐趣的智能解决方案 你是否每天需要花费大量时间在《鸣潮》中重复刷副本、收集资源、完成日常任务当工作学习繁忙时是否希望有一个助手能帮GUI 自动化计算机视觉RPA人工智能python-docx 表格对齐完全指南WD_TABLE_ALIGNMENT 枚举与 Table.alignment 实战python docx 表格对齐完全指南WD_TABLE_ALIGNMENT 枚举与 Table.alignment 实战 本文围绕 python docx后端上一篇Apache Zeppelin 部署到 CDHCloudera Distribution Hadoop集群基于 QuickStart Docker 的完整实战指南下一篇OWASP Top 10 2025 深度解读A07 认证失败Authentication Failures的风险面、攻击场景与防护实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考