PHPWord 0.14.0 版本特性深度解析:从脚注编号控制、语言支持到文档保护与批注

原创2026-09-27 14:27:511,696 阅读
文章标签:文档模板引擎

PHPWord 0.14.0 版本特性深度解析:从脚注编号控制、语言支持到文档保护与批注

导读

PHPWord 是 PHP 生态中广为人知的纯 PHP 读写 Word 文档的库(项目主页)。0.14.0 是其发展历程中承上启下的一个重要版本:它首次宣布了对 PHP 7.0/7.1 的兼容,同时一口气引入了脚注编号控制、字符串图像、注释(Comments)、段落上下文间距(ContextualSpacing)、文档级语言设置、密码保护、字段自动更新等一批新能力,并修复了从 Word 97 读取、PDF 图片输出到 PHP 7.2 兼容性的大量问题。本文将以 docs/changes/0.x/0.14.0.md 变更记录为骨架,逐一结合 src/PhpWord 下的源码实现与 samples、tests 中的真实用例,讲解每个特性的 API 形态、底层机制与实战用法,帮助你理解 0.14.0 引入的现代 API 并安全迁移旧代码。

版本概况:一次「兼容性 + 功能」的双重里程碑

0.14.0 于 2017 年 12 月 29 日发布。官方变更记录的核心结论有两句:修复了若干缺陷并新增了一批特性,同时带来了 PHP 7.0 与 7.1 的兼容性。从仓库源码可以看到,本版本对应的 API 底座已经具备现代形态:

  • 新增 Metadata\Settings 类(src/PhpWord/Metadata/Settings.php),并在 PhpWord 主类中提供 getSettings() 入口(src/PhpWord/PhpWord.php),文档级配置从「散落各处」走向「统一设置中心」;
  • 新增 SimpleType\NumberFormat、SimpleType\TextAlignment 等简单类型枚举(src/PhpWord/SimpleType),开始用枚举类收敛 OOXML 属性取值;
  • PhpWord::__construct() 中统一注册 Bookmarks、Titles、Footnotes、Endnotes、Charts、Comments 六类集合(src/PhpWord/PhpWord.php),注释/脚注等元素以「集合 + 文档部件」的方式管理。

下文按「新增特性」「缺陷修复」「弃用与迁移」三大部分展开,并给出可直接运行的示例。

新增特性详解

1. 脚注编号控制(Footnote numbering)

0.14.0 允许开发者精细控制脚注的编号格式、起始值与重新开始策略。这一能力在源码中由两个类支撑:

  • ComplexType\FootnoteProperties(src/PhpWord/ComplexType/FootnoteProperties.php)定义了四个可配置项:
    • 位置(pos):pageBottom(页脚)、beneathText(文字下方)、sectEnd(节末)、docEnd(文档末尾);
    • 编号格式(numFmt):取值必须通过 NumberFormat::validate() 校验,即只能是 SimpleType\NumberFormat 中定义的值;
    • 起始值(numStart):脚注/尾注编号从几开始;
    • 重新开始策略(numRestart):continuous(连续编号)、eachSect(每节重新开始)、eachPage(每页重新开始)。 非法取值会抛出 InvalidArgumentException,属于严格的枚举约束。
  • SimpleType\NumberFormat(src/PhpWord/SimpleType/NumberFormat.php)自 0.14.0 起作为标准简单类型引入,覆盖了 OOXML ST_NumberFormat 的全部常见取值:decimal、upperRoman、lowerRoman、upperLetter、lowerLetter、ordinal、cardinalText、ordinalText、hex、chicago,以及面向东亚排版的大量格式(ideographDigital、japaneseCounting、aiueo、iroha、koreanDigital、chineseCounting 等),甚至包含 bullet、none、hebrew1、hebrew2、arabicAlpha、arabicAbjad、thaiLetters 等特殊编号,总计约 70 个常量。

从测试 tests/PhpWordTests/Writer/Word2007/Part/DocumentTest.php 可以看到,这些设置最终会写入 docx 的节属性中:/w:document/w:body/w:sectPr/w:footnotePr/w:numFmt、w:numStart、w:numRestart,即 OOXML 的 w:footnotePr 元素。

2. 从字符串创建图像(Image creation from string)

此前 addImage() 只能接受本地文件、GD 生成的图像或 zip 归档中的图像。0.14.0 起支持直接传入图片二进制字符串。在 src/PhpWord/Element/Image.php 中新增了源类型常量:

const SOURCE_LOCAL = 'local';   // 本地图片
const SOURCE_GD = 'gd';         // GD 生成
const SOURCE_ARCHIVE = 'archive'; // zip://$archive#$image
const SOURCE_STRING = 'string'; // 字符串图片(0.14.0 新增)

其判定逻辑位于 setSourceType():当传入内容包含 \0(二进制特征)或不是已存在的文件路径、也不是 URL 时,即判定为 SOURCE_STRING。底层使用 getimagesizefromstring() 读取尺寸与类型,支持 JPEG/GIF/PNG(字符串源不支持 BMP/TIFF 的解码尺寸读取,但可以通过 GD 重新编码)。getImageStringData() 可将图片输出为十六进制或 base64 编码,供 HTML 等 Writer 内嵌使用。典型场景是把「运行时生成」的图片(例如验证码、动态图表)直接塞进文档,无需落地临时文件。

3. 隐藏拼写与语法错误标记

0.14.0 允许在生成的 Word 文档中隐藏拼写错误与语法错误的波浪线。实现位于 src/PhpWord/Metadata/Settings.php:

$phpWord->getSettings()->setHideSpellingErrors(true);
$phpWord->getSettings()->setHideGrammaticalErrors(true);

对应属性 hideSpellingErrors、hideGrammaticalErrors 默认均为 false,传入 null 时被当作 true 处理。写出为 docx 后对应 w:settings 下的 w:hideSpellingErrors 与 w:hideGrammaticalErrors 元素(见 tests/PhpWordTests/Writer/Word2007/Part/SettingsTest.php)。适合交付正式文档时去除红色/蓝色波浪线干扰。

4. 文档默认语言与逐元素语言切换

这是 0.14.0 的另一个重要特性:既可以设置整个文档的默认语言,也可以为每个文本元素单独指定语言。

  • 文档级语言:Settings::setThemeFontLang(Language $lang)(src/PhpWord/Metadata/Settings.php),写出为 w:settings/w:themeFontLang;
  • 元素级语言:新增 src/PhpWord/Style/Language.php 样式类,它继承 AbstractStyle,内置大量预置常量,例如 EN_US、EN_GB、FR_FR、DE_DE、JA_JP、ZH_CN、HE_IL、RU_RU 等,并为每个语言附带了对应 RTF 使用的 Language ID(如 EN_US_ID = 1033、ZH_CN_ID = 2052)。

Language 类同时管理三个语种槽位:latin(西文)、eastAsia(东亚,如中日韩)、bidirectional(复杂文种,如希伯来、阿拉伯)。validateLocale() 会做格式校验:zh_CN 会被自动规范化为 zh-CN,两位代码会展开为 xx-XX,und 被映射为 en-EN,不合法的单段代码(不含 - 且不是 zxx)会抛出 InvalidArgumentException。该特性对多语言模板、RTL(从右到左)文档尤为重要。

5. 注释(Comments)支持

0.14.0 让 PHPWord 具备了生成 Word 批注(comment)的能力。核心是 src/PhpWord/Element/Comment.php,它继承自 TrackChange,可携带 author(作者)、date(时间)、initials(缩写),并通过 setStartElement() / setEndElement() 或反向的 AbstractElement::setCommentRangeStart() / setCommentRangeEnd() 与文档中的具体元素建立批注区间。从 samples/Sample_37_Comments.php 可以看到三种典型用法:

// 1) 简单批注:评论挂在文字上
$comment = new PhpOffice\PhpWord\Element\Comment('Authors name', new DateTime(), 'my_initials');
$comment->addText('Test', ['bold' => true]);
$phpWord->addComment($comment);

$textrun = $section->addTextRun();
$text = $textrun->addText('is');
$text->setCommentRangeStart($comment);

// 2) 起止元素包围的批注区间
$textToStartOn->setCommentRangeStart($commentWithStartAndEnd);
$textToEndOn->setCommentRangeEnd($commentWithStartAndEnd);

// 3) 反向绑定:从 Comment 指向元素
$comment1->setStartElement($anotherText);
$comment1->setEndElement($anotherText);
$phpWord->addComment($comment1);

注释可以添加到图片等元素上($image->setCommentRangeStart($commentOnImage)),且支持多个批注共享同一区间。PhpWord 主类通过 addComment() 动态方法将批注归入 Collection\Comments(src/PhpWord/PhpWord.php),写出时由 Word2007 Writer 生成 comments.xml 部件。

6. 段落 textAlignment 支持

段落样式新增 textAlignment 选项,用于控制一行内文字(相对于行高)的垂直对齐,取值由 src/PhpWord/SimpleType/TextAlignment.php 约束。在 src/PhpWord/Style/Paragraph.php 中以 textAlignment 属性保存,写文档时输出到 w:jc/w:textAlignment 对应属性,适用于需要精确控制行内基线(如混合大小字号)的排版场景。

7. addHtml 增强:<u> 下划线与 <br> 换行

HTML 导入能力在 0.14.0 得到补强:

  • <u> 标签现在会被识别为下划线;
  • <br> 标签现在会被正确转换为换行。

这两个改动让 addHtml() 从纯文本/粗斜体的支持扩展到更接近真实 HTML 片段。同时 0.14.0 还支持了 HTML <img> 标签,src/PhpWord/Shared/Html.php 中负责解析 HTML 片段并生成对应元素,配合「字符串图像」特性,可以用 <img src="data:..."> 或外链图片渲染富文本内容。

8. 单元格宽度单位可切换

Style\Cell(src/PhpWord/Style/Cell.php)在 0.14.0 允许指定宽度单位。底层引入 SimpleType\TblWidth 枚举(auto、percent、twip),单元格宽度默认单位为 TWIP(TblWidth::TWIP),通过 setUnit() 可切换为百分比(percent)或自动(auto)。当使用百分比单位时,单元格宽度按表格宽度比例计算,便于制作响应式比例的表格布局。

9. 行高规则(Line height rule)可配置

段落样式的行高规则在 0.14.0 可调整,配合 SimpleType\LineSpacingRule 枚举(auto、exact、atLeast),在 src/PhpWord/Style/Paragraph.php 的 lineHeight/spacing 体系中体现:exact 表示固定行距、atLeast 表示最小行距、auto 表示自动。这对精确控制多语言混合文档的行距很有价值。

10. ODT Writer 的 PageBreak

ODText Writer 在 0.14.0 实现了分页符(PageBreak)支持。此前 addPageBreak() 仅对 docx 等格式有效,本版本补齐了 ODT 输出,使同一份文档模型可以同时导出 docx 与 odt 而保持分页语义一致。相关元素位于 src/PhpWord/Element/PageBreak.php,写出逻辑在 src/PhpWord/Writer/ODText 系列部件中。

11. 打开文档时强制更新所有域(updateFields)

文档设置新增「打开时自动更新域」开关:

$phpWord->getSettings()->setUpdateFields(true);

对应 w:settings/w:updateFields(见 tests/PhpWordTests/Writer/Word2007/Part/SettingsTest.php)。开启后,Word 打开文档时会重新计算 TOC、页码、日期等域代码,避免「打开文档后域值过期」的常见问题,对模板类文档尤其实用。

12. TextRun 内添加 CheckBox

0.14.0 允许把复选框(CheckBox)放入 TextRun 容器。Element\CheckBox(src/PhpWord/Element/CheckBox.php)继承自 Text,构造参数为 (name, text, fontStyle, paragraphStyle),setName() 会经 Shared\Text::toUTF8() 规范化。用法:

$textrun->addCheckBox('agree', 'I agree to the terms', ['bold' => true]);

复选框会以符号(如 ☑/☐)形式出现在文本流中,适合表单式文档。

13. docx 密码保护

0.14.0 支持为 docx 设置打开密码。底层是 src/PhpWord/Metadata/Protection.php 与 src/PhpWord/Shared/Microsoft/PasswordEncoder.php。注意:0.14.0 明确弃用了 PhpWord->getProtection(),改为从设置中心获取:

$protection = $phpWord->getSettings()->getDocumentProtection();
$protection->setEditing(DocProtect::READ_ONLY); // 限制编辑
// 或设置打开密码相关属性

Protection 的编辑限制取值由 SimpleType\DocProtect 约束,最终写入 docx 的 w:settings 部件,实现「只读/仅批注/仅填写表单」等文档保护。密码哈希采用 Microsoft 兼容算法(见 src/PhpWord/Shared/Microsoft/PasswordEncoder.php),确保 Word 能识别。

14. 其他新增

  • 奇偶页页眉页脚:Settings::setEvenAndOddHeaders(true)(src/PhpWord/Metadata/Settings.php)允许设置不同的偶数页与奇数页页眉/页脚;
  • 编号格式补全:NumberFormat 枚举为编号补上了之前缺失的大量格式选项(见上文枚举清单);
  • 首行页脚独立:可为首页设置不同的页脚。

缺陷修复与兼容性改进

PHP 7.x 兼容性

  • 修复若干 PHP 7.0/7.1 的警告(@likeuntomurphy);
  • PHP 7.2 兼容性:将名为 Object 的类重命名为 ObjectElement。当前仓库中可见 src/PhpWord/Element/OLEObject.php(OLE 对象元素)与对应的 src/PhpWord/Writer/Word2007/Element/OLEObject.php。由于 PHP 7.2 起 Object 成为保留字,任何直接使用旧类名的代码都必须迁移;
  • 放宽对 Zend 的依赖绑定,降低安装冲突概率。

Writer / Reader 修复

  • PDF 图片不打印:修复了生成 PDF 时图片缺失的问题(此前受 #431(DomPDF/MPDF/TCPDF);
  • HTTPS 图片加载:修复通过 https:// 加载远程图片失败的问题。在 src/PhpWord/Element/Image.php 的 setSourceType() 中可以看到,HTTPS 源会被 file_get_contents() 拉取为字符串并转为 SOURCE_STRING,HTTP 源则走 GD 路径——这就是该修复的最终落点;
  • HTML Writer 样式:修复 HTML 写出时样式未应用的问题,并改善 PDF 输出(@sarke,相关测试 tests/PhpWordTests/Writer/HTML);
  • docx 含远程图片 URL 的读取错误:读取包含远程 URL 图片的 docx 不再报错;
  • Windows 与 Mac 间图片尺寸不一致:修正因像素密度差异导致的图片显示尺寸偏差;
  • HTML 表格加入文档:修复通过 addHtml() 加入 <table> 时出错的问题;
  • w:val 取值解析:修复 Word2007 读取时对 true|false|1|0|on|off 等 on/off 值的解析(@troosan,对应 src/PhpWord/Reader/Word2007/AbstractPart.php 中 READ_TRUE 的取值矩阵);
  • 空下拉选项:修复空下拉条目(Dropdown 为空)导致读取失败的问题;
  • Word2007 读取多余段落:修复读取时产生非必要空段落的问题;
  • Word2007 页边距读取:修复页边距读取不正确的缺陷。

元素与结构修复

  • Section 中无法添加 PreserveText:修复后可在节中直接使用 addPreserveText(),保留「域代码文本」的原始形态;
  • 奇偶页 / 首页页脚:修复无法为奇数页与偶数页设置不同页眉、无法为首页设置不同页脚的问题(evenAndOddHeaders 与首页页脚配合使用);
  • **args数组补齐∗∗:修复动态方法调用中‘args 数组补齐**:修复动态方法调用中 `args未补齐导致的部分错误(见 <a href="https://link.gitcode.com/i/8fcf8c034e5e496b5c208f8c5ddc2a7e" target="_blank">src/PhpWord/PhpWord.php</a> 的__call中$args[0] ?? null` 的兜底逻辑);
  • Word 97 读取器:修复旧版二进制 .doc 的读取问题,读取器位于 src/PhpWord/Reader/MsDoc.php。

弃用与迁移指引

0.14.0 唯一的弃用项是:

PhpWord->getProtection() 已弃用,请改为通过设置中心获取:$phpWord->getSettings()->getDocumentProtection()。

这也体现了 0.14.0 的整体架构方向——文档级元数据统一收敛到 Metadata\Settings。迁移示例:

// 旧写法(0.14.0 起弃用)
$protection = $phpWord->getProtection();

// 新写法
$protection = $phpWord->getSettings()->getDocumentProtection();

Metadata\Settings 自此承担了文档保护、拼写隐藏、奇偶页眉、主题语言、字段更新、缩放、镜像边距、修订跟踪(trackRevisions、doNotTrackMoves、doNotTrackFormatting、revisionView)与校对状态(proofState)等全部文档级配置,成为后续版本扩展的基石。

实战组合示例

综合上述特性,一个覆盖 0.14.0 主要新能力的典型用法如下:

$phpWord = new PhpOffice\PhpWord\PhpWord();

// 文档级设置(Settings 中心)
$settings = $phpWord->getSettings();
$settings->setUpdateFields(true);                  // 打开时更新域
$settings->setHideSpellingErrors(true);            // 隐藏拼写错误波浪线
$settings->setHideGrammaticalErrors(true);         // 隐藏语法错误波浪线
$settings->setEvenAndOddHeaders(true);             // 奇偶页页眉分离
$settings->setThemeFontLang(
    new PhpOffice\PhpWord\Style\Language('en-US', 'zh-CN') // 文档默认语言
);
$settings->getDocumentProtection()->setEditing(
    PhpOffice\PhpWord\SimpleType\DocProtect::READ_ONLY
); // 文档只读保护

// 字符串图像(无需临时文件)
$pngData = imagepng(...); // 或 file_get_contents('data:...')
$section->addImage($pngData, ['width' => 100, 'height' => 50]);

// TextRun 中的复选框
$textrun->addCheckBox('agree', 'I agree', ['bold' => true]);

// 批注
$comment = new PhpOffice\PhpWord\Element\Comment('Author', new DateTime(), 'au');
$comment->addText('请复核此段');
$phpWord->addComment($comment);
$text = $section->addText('重点段落');
$text->setCommentRangeStart($comment);

保存为 docx 后,以上设置分别体现在 word/settings.xml(字段更新、拼写隐藏、保护、语言)、word/comments.xml(批注)与正文部件中。

总结

0.14.0 是 PHPWord 走向「设置中心化 + 枚举化 + PHP 7 原生」的关键版本:Metadata\Settings 与 SimpleType\NumberFormat/TextAlignment/TblWidth 等简单类型的引入,为后续 API 的稳定演进铺平了道路;字符串图像、批注、文档级语言、密码保护等能力则直接补齐了企业级文档生成的高频需求。对升级者而言,重点留意两处迁移:getProtection() 改走 getSettings(),以及 Object 类名在 PHP 7.2+ 下的重命名。相关变更的完整条目可查阅 docs/changes/0.x/0.14.0.md,各特性的源码与测试用例可在 src/PhpWord、samples 与 tests/PhpWordTests 中进一步研读。

登录后查看全文
PHPWord