PHPWord 批注（Comment）元素完全指南：创建评论、绑定文本范围与 Word/ODF 多格式写出-育师

后端

【免费下载链接】PHPWord

A pure PHP library for reading and writing word processing documents

项目地址：https://gitcode.com/gh_mirrors/ph/PHPWord

导读

本文聚焦 PHPWord（PHPWord，一款纯 PHP 读写 Word 处理文档的库）中的Comment（批注/评论）元素。文档批注是协作审阅场景的核心能力——你可以在生成 .docx 或 .odt 时程序化地插入带作者、日期、格式内容的批注，并将其精准挂接到正文的某个文字、段落甚至图片上。读完本文，你将掌握 Comment 元素的完整创建流程、setCommentRangeStart/setCommentRangeEnd的两种绑定方式、自动结束规则，以及 Word2007 与 ODF 两种格式下批注的底层序列化与回读原理。

Comment 元素是什么

在 PHPWord 中，批注通过PhpOffice\PhpWord\Element\Comment类表示。从源码继承链看：

Comment 继承自 TrackChange，因此天然具备作者（author）、日期（date）等修订元数据；
TrackChange又继承自AbstractContainer，意味着一个批注本身就是一个容器，可以容纳格式化文本、文本块（TextRun）等内容；
批注元素被标记为$collectionRelation = true，即它隶属于文档级的集合（Collection），通过PhpWord实例统一管理（见 src/PhpWord/Element/Comment.php）。

第一步：创建一条批注

Comment构造函数签名（见 src/PhpWord/Element/Comment.php#L65-L69）：

public function __construct($author, $date = null, $initials = null)

参数	类型	说明
`$author`	string	批注作者姓名，必填
`$date`	null \|`DateTime`	批注创建时间，可省略（省略后写入时该字段留空）
`$initials`	null \| string	作者缩写，可省略；Word 界面中用于标识批注气泡

创建示例：

$comment = new \PhpOffice\PhpWord\Element\Comment('Authors name', new DateTime(), 'my_initials');

第二步：向批注填充格式化内容

由于Comment继承自AbstractContainer，可以直接在批注内部添加与正文容器相同的子元素，最常见的是带样式文本：

// 添加一段加粗文本 $comment->addText('Test', ['bold' => true]); // 也可以添加一个完整的文本块（TextRun） $imageComment = $comment->addTextRun(); $imageComment->addText('Hey, Mars does look '); $imageComment->addText('red', ['color' => 'FF0000']);

这些内容最终会被序列化进文档的批注存储中，支持 Word / ODF 的富文本批注展示。

第三步：将批注注册到文档

创建好的批注必须通过PhpWord::addComment()注册到文档对象：

$phpWord->addComment($comment);

从实现上看，addComment与getComments()都是 PhpWord 通过__call动态分派的方法（见 src/PhpWord/PhpWord.php#L116-L120），其背后维护了一个PhpOffice\PhpWord\Collection\Comments集合（见 src/PhpWord/Collection/Comments.php）。批注与书签、脚注、图表一样，属于文档级的"独立存储"元素，而不是直接内嵌在某个段落里。

第四步：把批注挂接到正文元素（核心操作）

批注本身并不出现在正文流中，它必须锚定到正文中的某个元素才有意义。文档提供的关键方法是AbstractElement::setCommentRangeStart()，几乎所有元素（文本、段落内文本、图片、形状、OLE 对象、文本框等）都继承自 AbstractElement，因此都可以挂接批注。

方式一：从元素侧绑定批注（文档推荐方式）

$textrun = $section->addTextRun(); $textrun->addText('This '); $text = $textrun->addText('is'); // 将批注的开始点挂到刚创建的文本元素上 $text->setCommentRangeStart($comment); $textrun->addText(' a test');

批注会以"评论范围"（comment range）的形式锚定在'is'这个文本元素上。如果只设置了开始、不设置结束，PHPWord 会在该元素自然结束时自动终结批注范围——这正是文档中明确声明的行为：

If no end is set for a comment using thesetCommentRangeEnd, the comment will be ended automatically at the end of the element it is started on.

方式二：显式设置结束点

当批注需要横跨多个元素时，用setCommentRangeEnd明确指定结束元素：

$textrunWithEnd = $section->addTextRun(); $textrunWithEnd->addText('This '); $textToStartOn = $textrunWithEnd->addText('is', ['bold' => true]); $textToStartOn->setCommentRangeStart($commentWithStartAndEnd); $textrunWithEnd->addText(' another', ['italic' => true]); $textToEndOn = $textrunWithEnd->addText(' test'); $textToEndOn->setCommentRangeEnd($commentWithStartAndEnd);

这样批注范围就精确覆盖"is ～ test"之间的文本。

方式三：从批注侧反向绑定

Comment本身也提供setStartElement()/setEndElement()反向方法（见 src/PhpWord/Element/Comment.php#L84-L107），二者会回调对应元素的setCommentRangeStart/setCommentRangeEnd，效果等价：

$anotherText = $section->addText('another text'); $comment1 = new \PhpOffice\PhpWord\Element\Comment('Authors name', new DateTime(), 'my_initials'); $comment1->addText('Test', ['bold' => true]); $comment1->setStartElement($anotherText); $comment1->setEndElement($anotherText); $phpWord->addComment($comment1);

多个批注可以锚定到同一个元素上，实现"一处文本、多条批注"的效果（见 Sample_37_Comments.php 中$lastText同时挂两条批注的示例）。

完整可运行示例

综合以上步骤，一个最小可运行的完整脚本如下（同时覆盖"自动结束"与"显式结束"两种场景）：

<?php require_once 'vendor/autoload.php'; use PhpOffice\PhpWord\PhpWord; use PhpOffice\PhpWord\Element\Comment; $phpWord = new PhpWord(); // 1. 创建一条批注（自动结束范围） $comment = new Comment('Authors name', new DateTime(), 'my_initials'); $comment->addText('Test', ['bold' => true]); $phpWord->addComment($comment); $section = $phpWord->addSection(); $textrun = $section->addTextRun(); $textrun->addText('This '); $text = $textrun->addText('is'); $text->setCommentRangeStart($comment); // 无 setCommentRangeEnd，随该元素自动结束 $textrun->addText(' a test'); $section->addTextBreak(2); // 2. 创建一条显式设置起止范围的批注 $commentWithStartAndEnd = new Comment('Foo Bar', new DateTime()); $commentWithStartAndEnd->addText('A comment with a start and an end'); $phpWord->addComment($commentWithStartAndEnd); $textrunWithEnd = $section->addTextRun(); $textrunWithEnd->addText('This '); $textToStartOn = $textrunWithEnd->addText('is', ['bold' => true]); $textToStartOn->setCommentRangeStart($commentWithStartAndEnd); $textrunWithEnd->addText(' another', ['italic' => true]); $textToEndOn = $textrunWithEnd->addText(' test'); $textToEndOn->setCommentRangeEnd($commentWithStartAndEnd); // 3. 写出 $phpWord->save('comments.docx'); $phpWord->save('comments.odt');

更完整的官方示例（包括把批注挂到图片上）可直接参考 samples/Sample_37_Comments.php。

底层实现原理：范围绑定如何工作

AbstractElement::setCommentRangeStart()的实现（src/PhpWord/Element/AbstractElement.php#L314-L333）揭示了几个关键细节：

禁止自我锚定：如果元素本身是Comment，会抛出InvalidArgumentException（"Cannot set a Comment on a Comment"），防止批注上再挂批注；
集合化存储：每个元素可以挂多条批注，内部用Collection\Comments保存，getCommentsRangeStart()/getCommentRangeEnd()返回整个集合；
ID 提前分配：在写入集合前会先为批注分配elementId（"Set ID early to avoid duplicates"），并通过 ID 去重，避免同一批注被重复挂接；
双向维护：集合写入后会回调Comment::setStartElement($this)，保证批注对象与锚定元素互为引用，写出端正是依赖这对引用关系来输出范围的。

setCommentRangeEnd()的实现与之完全对称（src/PhpWord/Element/AbstractElement.php#L358-L377）。

写出端：Word2007 与 ODF 的批注序列化

Word2007（.docx）

批注在 .docx 中分两处落地：

批注内容存储：所有批注汇总写入包内的comments.xml，由 Writer/Word2007/Part/Comments.php 负责，每条批注写出作者、日期、缩写（initials）以及内部容器承载的格式化内容；
正文锚点标记：正文各元素通过 Writer/Word2007/Element/AbstractElement.php 中的writeCommentRangeStart()/writeCommentRangeEnd()输出w:commentRangeStart/w:commentRangeEnd标记，并在文本运行内输出w:commentReference引用。图片、图表、形状、OLE 对象、文本框等元素同样在各自写出器中调用writeCommentRangeStart()（例如 Image.php）。

此外，Settings 部件支持通过修订视图（TrackChangesView）控制w:comments的显示开关，说明批注与修订（Track Changes）共用同一套文档设置体系。

ODF（.odt）

文档明确说明：ODF 写出器将批注序列化为原生 ODF 注解（annotations），包含作者、日期、格式化内容与批注范围。对应实现在 Writer/ODText/Element/AbstractElement.php：

范围起点写出office:annotation，并携带office:name（元素 ID）；
注解内部写出dc:creator（作者）、dc:date（格式化后的时间戳，格式如Y-m-d\TH:i:s\Z），随后用容器写出器（Container）输出批注内的格式化文本内容；
若批注未显式设置结束元素（getEndElement() === null），ODF 写出器会在范围起点处自动补写范围结束标记，与文档描述的自动结束规则一致。

读取端：从现有 .docx 中还原批注

PHPWord 的 Word2007 读取器同样支持回读批注：

Reader/Word2007/Comments.php 读取包内的批注存储，按作者、日期、缩写重建Comment元素并加入$phpWord->getComments()集合；
Reader/Word2007/AbstractPart.php 在解析正文时识别w:commentReference/w:commentRangeStart/w:commentRangeEnd标记，通过setCommentReference()记录批注 ID 与对应元素的映射，最后回填到每个元素的setCommentRangeStart/setCommentRangeEnd上，完整还原批注锚点。

小结

PHPWord 的 Comment 元素提供了一条简洁而完整的批注链路：构造（作者 + 日期 + 缩写）→ 容器内填充格式化内容 →addComment注册到文档 → 通过setCommentRangeStart/setCommentRangeEnd锚定正文元素（或反向通过setStartElement/setEndElement）→ 由 Word2007/ODF 写出器分别序列化为comments.xml与原生注解。无论你是需要在生成的合同、报告或协作文档中预置审阅批注，还是需要解析既有文档中的批注数据，都可以直接复用本文的 API 与实现路径。