后端【免费下载链接】PHPWordA pure PHP library for reading and writing word processing documents项目地址https://gitcode.com/gh_mirrors/ph/PHPWord点击查看免费下载本文基于 PHPWord 官方文档 docs/usage/elements/table.md 展开系统讲解在 Section 中创建表格、行、单元格的核心 API以及通过addTableStyle定义可复用表格样式、通过gridSpan与vMerge实现跨列与跨行合并的完整用法。读完本文你将能够在 PHPWord 中从零构建基础表格、精致样式表格、合并单元格表格、嵌套表格与浮动定位表格并理解其底层实现原理。一、表格的创建addTable / addRow / addCell在 PHPWord 中表格是挂在 Section 之下的容器元素由「表格 → 行 → 单元格」三层结构组成。创建一张表格只需三个方法调用?php $table $section-addTable([$tableStyle]); $table-addRow([$height], [$rowStyle]); $cell $table-addCell($width, [$cellStyle]);$section-addTable($style)向当前 Section 添加一个表格。$style既可以传入内联样式数组也可以传入已注册的样式名称字符串不传则使用默认样式。$table-addRow($height, $style)添加一行$height指定行高单位 twip$style为行样式数组。$table-addCell($width, $style)添加单元格$width为单元格宽度单位 twip$style为单元格样式数组。从源码看Table::addRow() 会创建Row对象并设置其父容器为表格Table::addCell() 则将单元格挂到当前最后添加的行上。单元格继承自AbstractContainer见 Element/Cell.php因此addCell()的返回值可以直接调用addText()、addImage()等容器方法写入内容形成$table-addCell($width)-addText(...)的链式写法。基础表格示例?php $phpWord new PhpOffice\PhpWord\PhpWord(); $section $phpWord-addSection(); $rows 10; $cols 5; $table $section-addTable(); for ($r 1; $r $rows; $r) { $table-addRow(); for ($c 1; $c $cols; $c) { $table-addCell(1750)-addText(Row {$r}, Cell {$c}); } }以上代码生成一张 10 行 5 列、每列宽 1750 twip 的基础表格完整可运行版本见 samples/Sample_09_Tables.php 的第 1 节。二、用 addTableStyle 定义可复用表格样式当同一张表格样式需要被多次使用例如整套文档统一边框与表头底色时推荐先用PhpWord::addTableStyle()注册命名样式再通过样式名引用?php $tableStyle array( borderColor 006699, borderSize 6, cellMargin 50 ); $firstRowStyle array(bgColor 66BBFF); $phpWord-addTableStyle(myTable, $tableStyle, $firstRowStyle); $table $section-addTable(myTable);addTableStyle(string $styleName, mixed $styleTable, mixed $styleFirstRow null)的三个参数分别是样式名称、表格样式数组、首行样式数组可选。从 PhpWord::addTableStyle() 的方法签名可以看到首行样式是独立于表格样式传入的。其底层实现位于 Style/Table.php 的构造函数当传入$firstRowStyle时会先克隆当前表格样式禁用边框内部线borderInside*、单元格边距cellMargin*与cellSpacing等「仅表格层生效」的属性对应 getTableOnlyProperty / setTableOnlyProperty 的保护逻辑再套用首行样式。这意味着首行样式天然继承表格样式的外边框与底色基调只需覆盖需要差异化的属性即可。进阶首行 单元格样式组合samples/Sample_09_Tables.php第 2 节给出了更完整的组合用法将表格样式、首行样式、单元格样式、字体样式四层叠加?php $fancyTableStyleName Fancy Table; $fancyTableStyle [ borderSize 6, borderColor 006699, cellMargin 80, alignment PhpOffice\PhpWord\SimpleType\JcTable::CENTER, cellSpacing 50, ]; $fancyTableFirstRowStyle [ borderBottomSize 18, borderBottomColor 0000FF, bgColor 66BBFF, ]; $fancyTableCellStyle [valign center]; $fancyTableCellBtlrStyle [ valign center, textDirection PhpOffice\PhpWord\Style\Cell::TEXT_DIR_BTLR, ]; $fancyTableFontStyle [bold true]; $phpWord-addTableStyle($fancyTableStyleName, $fancyTableStyle, $fancyTableFirstRowStyle); $table $section-addTable($fancyTableStyleName); $table-addRow(900); $table-addCell(2000, $fancyTableCellStyle)-addText(Row 1, $fancyTableFontStyle); // ... 其余单元格同理这里alignment使用的是表格专用的对齐枚举JcTablestart/center/end见 SimpleType/JcTable.phptextDirection则来自Style\Cell的常量TEXT_DIR_BTLR自底向上、从左到右的文字方向见 Style/Cell.php。三、表格、行、单元格的完整样式参数表格级样式Table完整的表格样式选项在 docs/usage/styles/table.md 中定义对应源码类为 Style/Table.php其继承自Border因此边框类参数全部可用参数说明取值/示例alignment表格对齐方式见SimpleType\JcTable与SimpleType\Jc类常量start/center/end等bgColor表格背景色如9966CCborder(Top\|Right\|Bottom\|Left)Color各边边框颜色如9966CCborder(Top\|Right\|Bottom\|Left)Size各边边框粗细单位 twip整数cellMargin(Top\|Right\|Bottom\|Left)单元格边距单位 twip整数indent表格相对左页边距的缩进必须是ComplexType\TblWidth实例width表格宽度以五十分之一百分比pct或二十分之一磅dxa/twip为单位unit宽度单位SimpleType\TblWidth常量之一默认autolayout表格布局fixed或autofitStyle\Table::LAYOUT_AUTO/LAYOUT_FIXED见 Style/Table.phpcellSpacing单元格间距单位 twip整数position浮动表格定位见下文「浮动表格定位选项」bidiVisual以从右到左方式呈现表格布尔值宽度单位枚举见 SimpleType/TblWidth.phpnil无宽度、auto自动计算默认、pct五十分之一百分比、dxa二十分之一磅即 twip。设置百分比宽度时需自行换算50% 写成50 * 502500示例见Sample_09_Tables.php第 5 节[width 50 * 50, unit pct, alignment JcTable::CENTER]。表格布局枚举LAYOUT_AUTOautofit默认与LAYOUT_FIXEDfixed定义于 Style/Table.php对应 OOXML 标准w:tblLayout的两种取值。浮动表格定位选项position当表格需要脱离文档流、环绕于文字周围时使用position数组开启浮动定位参数说明取值leftFromText表格左侧距文字的距离twip整数rightFromText表格右侧距文字的距离twip整数topFromText表格顶部距文字的距离twip整数bottomFromText表格底部距文字的距离twip整数vertAnchor表格垂直锚点Style\TablePosition::VANCHOR_*常量horzAnchor表格水平锚点Style\TablePosition::HANCHOR_*常量tblpXSpec相对锚点的水平对齐Style\TablePosition::XALIGN_*常量tblpX距锚点的绝对水平距离twip整数tblpYSpec相对锚点的垂直对齐Style\TablePosition::YALIGN_*常量tblpY距锚点的绝对垂直距离twip整数Sample_09_Tables.php第 6 节演示了结合Converter::cmToTwip()做单位换算的浮动表格?php use PhpOffice\PhpWord\Shared\Converter; use PhpOffice\PhpWord\Style\TablePosition; $table $section-addTable([ borderSize 6, borderColor 999999, position [ vertAnchor TablePosition::VANCHOR_TEXT, bottomFromText Converter::cmToTwip(1), ], ]);行级样式Row行样式定义于 Style/Row.php共三个布尔开关参数说明默认cantSplit行不允许跨页断开falseexactHeight行高为精确值否则为「至少」高度falsetblHeader跨页时重复表头行false其中tblHeader用于长表格分页时每页顶部重复显示标题行cantSplit保证一行内容不被拆到两页。需要说明的是ODText 写入器将行高序列化为原生 ODF 表格行样式精确高度使用style:row-height「至少」高度使用style:min-row-height见 docs/usage/styles/table.md。单元格级样式Cell单元格样式对应 Style/Cell.php同样继承Border参数说明取值/示例bgColor单元格背景色如9966CCborder(Top\|Right\|Bottom\|Left)Color各边边框颜色如9966CCborder(Top\|Right\|Bottom\|Left)Size各边边框粗细twip整数border(Top\|Right\|Bottom\|Left)Style边框线型SimpleType\Border常量gridSpan跨列数colspan整数如 5textDirection(btLr\|tbRl)文字方向Style\Cell::TEXT_DIR_BTLR/TEXT_DIR_TBRL源码中还支持lrTb、lrTbV、tbRlV、tbLrV等常量见 Style/Cell.phpvalign垂直对齐top、center、both、bottomvMerge纵向合并restart或continuewidth单元格宽度twip整数关于 ODText 写入器单元格边框会被序列化为原生 ODF 表格单元格样式各边独立写入因此同一行内非对称边框、不同单元格的不同边框定义都能保留表格与单元格的bgColor会映射为原生 ODF 背景色单元格内边距、垂直对齐、文字方向、换行、列跨度、表格对齐与宽度在设置了对应样式时也会一并映射见 docs/usage/styles/table.md。四、单元格合并gridSpan 跨列、vMerge 跨行表格合并单元格有两种方式gridSpan让一个单元格横跨多列即 HTML 中的colspanvMerge让单元格纵跨多行即 HTML 中的rowspan通过restart开启合并、continue延续合并实现。gridSpan 跨列文档给出的最简用法?php $cell $table-addCell(200); $cell-getStyle()-setGridSpan(5);也可以直接在单元格样式数组中声明效果等价?php $cell $table-addCell(200, [gridSpan 5]);在 Word2007 写入器中gridSpan与vMerge会被序列化为 OOXML 的w:gridSpan与w:vMerge元素见 Writer/Word2007/Style/Cell.php保证生成的 docx 与 Word 原生合并行为一致。vMerge 跨行?php $row1 $table-addRow(); $row1-addCell(500)-addText(A); $row1-addCell(1000, [gridSpan 2])-addText(B); $row1-addCell(500, [vMerge restart])-addText(C); $row2 $table-addRow(); $row2-addCell(1500, [gridSpan 3])-addText(D); $row2-addCell(null, [vMerge continue]); // 延续 C 的合并 $row3 $table-addRow(); $row3-addCell(500)-addText(E); $row3-addCell(500)-addText(F); $row3-addCell(500)-addText(G); $row3-addCell(null, [vMerge continue]); // 再次延续关键规则合并起始单元格写vMerge restart后续行对应位置写vMerge continue延续单元格通常不需要宽度传null即可vMerge取值restart/continue对应 Style/Cell.php 中的VMERGE_RESTART与VMERGE_CONTINUE常量。上述代码对应Sample_09_Tables.php第 3 节的布局示意------------------------- | A | B | C | |-----|-----------| | | D | | ------|-----------| | | E | F | G | | -------------------------Sample_09_Tables.php第 4 节还演示了 gridSpan 与 vMerge 同时作用于同一单元格如[gridSpan 2, vMerge restart]的复合合并这是实现「先跨列再跨行」复杂表头布局的常用手法。五、进阶场景嵌套表格与 50% 宽度表格表格单元格本身是容器AbstractContainer因此可以在单元格内再嵌表格。Sample_09_Tables.php第 5 节演示了嵌套表格与百分比宽度?php use PhpOffice\PhpWord\SimpleType\JcTable; $table $section-addTable([ width 50 * 50, // 50% 宽度pct 单位下 ×50 换算 unit pct, alignment JcTable::CENTER, ]); $cell $table-addRow()-addCell(); $cell-addText(This cell contains nested table.); $innerCell $cell-addTable([ alignment JcTable::CENTER, ])-addRow()-addCell(); $innerCell-addText(Inside nested table);嵌套时只需在单元格对象上再次调用addTable()PHPWord 会自动维护父子容器关系外层表格通过unit pctwidth 2500实现 50% 相对宽度并居中内层表格同样居中展示。六、从源码理解表格的数据结构与列宽计算从源码结构看PHPWord 的表格对象模型是纯内存树Element\Table持有rows数组提供addRow()、addCell()、getRows()、countColumns()与findFirstDefinedCellWidths()等方法见 Element/Table.phpElement\Row持有height与cells数组addCell()创建Element\Cell见 Element/Row.phpElement\Cell继承自AbstractContainer宽度与样式在构造时注入见 Element/Cell.php。值得留意的是countColumns()的实现它遍历所有行并取「最大单元格数」作为列数而findFirstDefinedCellWidths()则按行序收集第一处定义了宽度的列宽序列见 Element/Table.php。这说明 PHPWord 允许不同行的单元格数量不一致最终列宽由各列单元格宽度协调决定——这也正是合并单元格场景下null宽度延续格能被正确推算的原因。七、运行示例与深入阅读Sample_09_Tables.php可在仓库根目录直接通过命令行或浏览器运行php samples/Sample_09_Tables.php它依次输出基础表格、Fancy Table、colspan/rowspan 合并表格、嵌套表格与浮动定位表格是本文全部要点的可运行合集。核心文档docs/usage/elements/table.md、docs/usage/styles/table.md完整示例samples/Sample_09_Tables.php元素实现src/PhpWord/Element/Table.php、src/PhpWord/Element/Row.php、src/PhpWord/Element/Cell.php样式实现src/PhpWord/Style/Table.php、src/PhpWord/Style/Row.php、src/PhpWord/Style/Cell.php枚举定义src/PhpWord/SimpleType/JcTable.php、src/PhpWord/SimpleType/TblWidth.phpOOXML 序列化src/PhpWord/Writer/Word2007/Style/Cell.php赞分享后端【免费下载链接】PHPWordA pure PHP library for reading and writing word processing documents项目地址https://gitcode.com/gh_mirrors/ph/PHPWord点击查看免费下载相关推荐Bodyguard安全考量防止权限提升攻击的10个关键防御策略Bodyguard安全考量防止权限提升攻击的10个关键防御策略 Bodyguard是Phoenix应用中用于权限控制的强大工具但如果不正确使用可能导致严重PHPWord表格操作终极指南10个高级技巧实现复杂单元格布局PHPWord表格操作终极指南10个高级技巧实现复杂单元格布局 PHPWord作为一款强大的PHP文档处理库能够轻松实现Word文档的创建和编辑功能。在前1后端ReactQuill 实现表格编辑合并单元格与样式定制完全指南ReactQuill 实现表格编辑合并单元格与样式定制完全指南 痛点直击富文本编辑器表格功能的三大困境 你是否在使用ReactQuill开发时遇到这些表格操前端UI组件上一篇Android Studio中文界面终极指南5分钟打造高效开发环境 下一篇llama.cpp Server buttons-top 主题指南把 Send/Stop 操作按钮固定在页面顶部PowerInfer 仓库实例创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考