- 后端
【免费下载链接】PHPWord
A pure PHP library for reading and writing word processing documents
本文围绕 PHPWord（纯 PHP 读写 Word 文档的开源库）中最基础的文本写入能力展开，系统讲解addText与addTextRun两种文本添加方式的适用场景、参数约定、字体与段落样式配置，并结合仓库源码与官方示例深入解析底层实现与修订跟踪（Track Changes）用法。读完本文，你将掌握在 Section、Cell、Header/Footer 等任意容器中写入格式化文本的完整方案，并能直接复用可运行代码。
一、两种文本添加方式：addText 与 addTextRun
在 PHPWord 中，文本通过addText与addTextRun两个方法写入。二者的选择标准是段落内部样式的复杂度：
addText：用于创建只包含同一样式的简单段落。一段文字整体使用一套字体样式和段落样式，一行代码即可完成。addTextRun：用于创建包含多种样式的复杂段落——同一段落内既有加粗、又有斜体、还有不同颜色、甚至嵌入图片或链接等元素时使用。
两者的基础语法如下（摘自 docs/usage/elements/text.md）：
<?php $section->addText($text, [$fontStyle], [$paragraphStyle]); $textrun = $section->addTextRun([$paragraphStyle]);三个参数的含义：
$text：要显示在文档中的文本内容。$fontStyle：字体样式。既可以是命名样式名，也可以是样式数组，可选项参见 Styles > Font。$paragraphStyle：段落样式。同样可以是命名样式名或样式数组，可选项参见 Styles > Paragraph。
从源码看，addText和addTextRun均声明在抽象容器类 AbstractContainer.php 的@method注释中，实际调用由__call魔术方法统一分派（AbstractContainer.php），并通过checkValidity校验当前容器是否允许添加该元素（AbstractContainer.php）。因此这两个方法在 Section、Header、Footer、Cell、TextBox 等几乎所有容器内都可用。
二、addText：简单段落文本
addText适合整段文字使用统一字体的场景。官方示例 Sample_01_SimpleText.php 展示了最基础与最常用的调用形式：
<?php $phpWord = new PhpOffice\PhpWord\PhpWord(); $section = $phpWord->addSection(); // 最简形式：仅文本 $section->addText('Hello World!'); // 使用命名字体样式 $fontStyleName = 'rStyle'; $phpWord->addFontStyle($fontStyleName, [ 'bold' => true, 'italic' => true, 'size' => 16, 'allCaps' => true, 'doubleStrikethrough' => true, ]); $section->addText('I am styled by a font style definition.', $fontStyleName); // 使用命名段落样式 $paragraphStyleName = 'pStyle'; $phpWord->addParagraphStyle($paragraphStyleName, [ 'alignment' => PhpOffice\PhpWord\SimpleType\Jc::CENTER, 'spaceAfter' => 100, ]); $section->addText('I am styled by a paragraph style definition.', null, $paragraphStyleName); // 同时应用字体与段落样式 $section->addText('I am styled by both font and paragraph style.', $fontStyleName, $paragraphStyleName); // 指定语言（法语示例） $section->addText('Ce texte-ci est en français.', ['lang' => PhpOffice\PhpWord\Style\Language::FR_BE]);可以看到，addText的三个参数可以按需省略：只传文本时不带任何样式；需要字体样式时传第二个参数并把段落样式置为null；只设置段落样式时第二个参数传null。
在 Text.php 的构造函数中，$fontStyle与$paragraphStyle可以是Font/Paragraph样式对象、样式名（字符串）或样式数组。传入数组时，源码会创建对应的样式对象并调用setStyleByArray批量赋值（Text.php、Text.php）。另外，文本内容在存储前会经过SharedText::toUTF8统一转码（Text.php），因此传入非 UTF-8 编码的中文、法语等文本也能被正确处理。
三、addTextRun：复杂段落文本
当一段文字内部需要混排多种字体样式（部分加粗、部分斜体、部分带下划线），或需要嵌入链接、图片、公式等其他元素时，应使用addTextRun。它返回一个TextRun容器对象，之后通过该对象上的一系列add*方法持续追加内容，所有追加的元素最终落在同一个段落内，由可选的段落样式统一控制布局。
官方示例 Sample_04_Textrun.php 给出了完整演示：
<?php $phpWord = new PhpOffice\PhpWord\PhpWord(); // 先定义命名样式 $paragraphStyleName = 'pStyle'; $phpWord->addParagraphStyle($paragraphStyleName, ['spacing' => 100]); $boldFontStyleName = 'BoldText'; $phpWord->addFontStyle($boldFontStyleName, ['bold' => true]); $coloredFontStyleName = 'ColoredText'; $phpWord->addFontStyle($coloredFontStyleName, ['color' => 'FF8080', 'bgColor' => 'FFFFCC']); $linkFontStyleName = 'NLink'; $phpWord->addLinkStyle($linkFontStyleName, [ 'color' => '0000FF', 'underline' => PhpOffice\PhpWord\Style\Font::UNDERLINE_SINGLE, ]); $section = $phpWord->addSection(); // 带段落样式的 TextRun：内部混排多种字体，并嵌入链接与图片 $textrun = $section->addTextRun($paragraphStyleName); $textrun->addText('Each textrun can contain native text, link elements or an image.'); $textrun->addText(' No break is placed after adding an element.', $boldFontStyleName); $textrun->addText(' Both '); $textrun->addText('superscript', ['superScript' => true]); $textrun->addText(' and '); $textrun->addText('subscript', ['subScript' => true]); $textrun->addText(' are also available.'); $textrun->addText(' All elements are placed inside a paragraph with the optionally given paragraph style.', $coloredFontStyleName); $textrun->addText(' Sample Link: '); $textrun->addLink('https://github.com/PHPOffice/PHPWord', 'PHPWord on GitHub', $linkFontStyleName); $textrun->addText(' Sample Image: '); $textrun->addImage(__DIR__ . '/resources/_earth.jpg', ['width' => 18, 'height' => 18]);要点：
- 每次
addText都会生成一个独立的Text元素，元素之间不会自动插入换行，需要换行时使用addTextBreak。 - 字体样式既可以用命名样式名，也可以用内联样式数组（如
['bold' => true]），后者只影响当前这一个Text元素。 TextRun内部还可以追加链接（addLink）、图片（addImage）、OLE 对象（addObject）、脚注（addFootnote）、表单域（addFormField）、公式（addFormula）等丰富元素，详见容器类的方法清单（AbstractContainer.php）。- 在
TextRun内追加纯文本时，段落样式参数会被容器内部强制移除（AbstractContainer.php），因为段落级样式已由addTextRun统一指定，避免重复设置。
TextRun类本身继承自AbstractContainer（TextRun.php），其getText()方法会遍历内部所有元素，将普通文本与 Ruby 注音文本拼接为纯字符串（TextRun.php），方便在读取回写或校验时提取段落全文。
四、字体样式（Font）完整选项
addText的第二个参数与TextRun内addText的样式参数均支持以下字体属性，完整清单出自 docs/usage/styles/font.md：
| 样式键 | 说明 | 取值示例 |
|---|---|---|
allCaps | 全大写 | true/false |
bgColor | 文字背景色 | FF0000（十六进制色值） |
bold | 加粗 | true/false |
color | 文字颜色 | FF0000 |
doubleStrikethrough | 双删除线 | true/false |
fgColor | 文字高亮色 | yellow、green、blue；可取值见\PhpOffice\PhpWord\Style\Font::FGCOLOR_...类常量 |
hint | 字体内容类型 | default、eastAsia、cs |
italic | 斜体 | true/false |
name | 字体名称 | Arial、Times New Roman |
rtl | 从右到左语言 | true/false |
size | 字号 | 20、22（半角点） |
smallCaps | 小型大写字母 | true/false |
strikethrough | 删除线 | true/false |
subScript | 下标 | true/false |
superScript | 上标 | true/false |
underline | 下划线类型 | single、dash、dotted等；可取值见\PhpOffice\PhpWord\Style\Font::UNDERLINE_...类常量 |
lang | 语言 | 语言代码如en-US、fr-BE，或需设置东亚/双向语言时的Language对象/数组；部分语言代码见\PhpOffice\PhpWord\Style\Language类 |
position | 文字位置（提升/降低） | 以半角点为单位 |
hidden | 隐藏文字 | true/false |
whiteSpace | 生成 HTML/PDF 时空白处理方式 | pre-wrap、normal（其他 CSS 值可接受，但一般无实际意义） |
fallbackFont | HTML/PDF 的通用回退字体 | sans-serif、serif、monospace（其他通用字体系列亦可） |
其中underline与fgColor的合法取值定义在 Font.php 的UNDERLINE_*与FGCOLOR_*类常量中；lang的常用语言代码（如EN_GB、FR_BE）定义在 Language.php。示例 Sample_01_SimpleText.php 对color、bold、italic、underline、strikethrough、superScript、subScript、smallCaps、allCaps、fgColor、spacing、kerning等内联样式均有实际调用，可直接参考。
提示：字体样式也可预先通过
$phpWord->addFontStyle('样式名', [...])注册为命名样式，然后在addText中直接传样式名复用，见 Sample_01_SimpleText.php。
五、段落样式（Paragraph）完整选项
addText的第三个参数与addTextRun的参数支持以下段落属性，完整清单出自 docs/usage/styles/paragraph.md：
| 样式键 | 说明 | 取值/单位 |
|---|---|---|
alignment | 对齐方式，支持 ECMA-376 第一版至 ISO/IEC 29500:2012 的所有对齐模式 | 见\PhpOffice\PhpWord\SimpleType\Jc类常量（如Jc::CENTER） |
basedOn | 父样式 | 样式名 |
hanging | 悬挂缩进 | 半英寸 |
indent | 左缩进 | 半英寸 |
indentation | 缩进键值对数组 | 以 twip 为单位，支持left、right、firstLine、firstLineChars、hanging，类型见\PhpOffice\PhpWord\Style\Indentation |
keepLines | 保持整段在同一页 | true/false |
keepNext | 与下一段保持同页 | true/false |
lineHeight | 行高倍数 | 1.0、1.5等 |
next | 下一段样式 | 样式名 |
pageBreakBefore | 从新页开始本段 | true/false |
spaceBefore | 段前间距 | twip |
spaceAfter | 段后间距 | twip |
spacing | 行间距 | twip；当spacingLineRule为auto时基准值 240（一行高度）会被自动加入，如需双倍行距请设为 240 |
spacingLineRule | 行距规则 | auto、exact、atLeast，见\PhpOffice\PhpWord\SimpleType\LineSpacingRule类常量 |
suppressAutoHyphens | 段落自动断字 | true/false |
tabs | 自定义制表位集合 | 制表位数组 |
widowControl | 允许首/末行单独显示于页面 | true/false |
contextualSpacing | 相同样式段落间忽略上下间距 | true/false |
bidi | 从右到左段落布局 | true/false |
shading | 段落底纹 | 着色样式 |
textAlignment | 行内垂直字符对齐 | 见\PhpOffice\PhpWord\SimpleType\TextAlignment类常量 |
对齐取值常量Jc定义于 Jc.php，行距规则LineSpacingRule定义于 LineSpacingRule.php，垂直对齐TextAlignment定义于 TextAlignment.php。与字体样式一样，段落样式既可以在调用处以内联数组给出，也可以通过$phpWord->addParagraphStyle()注册为命名样式后引用。
六、修订跟踪：将文本标记为插入或删除
如果要让新增文本在 Word 中体现"修订/审阅"标记，可以将其标记为INSERTED（插入）或DELETED（删除），并指定修订作者与时间。原文档 docs/usage/elements/text.md 给出了如下写法：
<?php $text = $section->addText('Hello World!'); $text->setChanged(\PhpOffice\PhpWord\Element\ChangedElement::TYPE_INSERTED, 'Fred', (new \DateTime()));需要说明的是：当前仓库源码中，修订标记的实际 API 位于 AbstractElement.php，名为setTrackChange与setChangeInfo，修订类型常量定义在 TrackChange.php（TrackChange::INSERTED/TrackChange::DELETED）。官方示例 Sample_39_TrackChanges.php 给出了当前推荐的完整写法：
<?php use PhpOffice\PhpWord\Element\TrackChange; $phpWord = new PhpOffice\PhpWord\PhpWord(); $section = $phpWord->addSection(); $textRun = $section->addTextRun(); // 方式一：setChangeInfo —— 传入类型、作者、时间 $text = $textRun->addText('wake ', ['bold' => true]); $text->setChangeInfo(TrackChange::INSERTED, 'Fred', time() - 1800); // 方式二：setTrackChange —— 传入 TrackChange 对象 $text = $textRun->addText('up'); $text->setTrackChange(new TrackChange(TrackChange::INSERTED, 'Fred')); // 标记为删除：指定作者与更早的时间戳 $text = $textRun->addText('go to sleep'); $text->setChangeInfo(TrackChange::DELETED, 'Barney', new DateTime('@' . (time() - 3600)));setChangeInfo($type, $author, $date)的三个参数中，$date既可以是DateTime对象，也可以是 Unix 时间戳整数，且统一按 UTC 处理（AbstractElement.php）；TrackChange构造函数对传入的整数时间戳会转换为DateTime('@' . $date)（TrackChange.php）。生成文档后，被标记的文字在 Word 中会显示为带修订记录的插入或删除内容，作者名与时间会出现在审阅窗格中。更多细节可参阅修订功能示例与 docs/usage/elements/trackchanges.md。
七、完整可运行示例
将以上内容组合为一个完整的脚本，即可生成一份同时包含简单文本、混排样式文本与修订标记的 Word 文档：
<?php require_once 'vendor/autoload.php'; use PhpOffice\PhpWord\Element\TrackChange; use PhpOffice\PhpWord\PhpWord; use PhpOffice\PhpWord\SimpleType\Jc; $phpWord = new PhpWord(); // 注册命名样式 $phpWord->addFontStyle('titleFont', ['bold' => true, 'size' => 22, 'color' => '333333']); $phpWord->addParagraphStyle('centerPara', ['alignment' => Jc::CENTER, 'spaceAfter' => 240]); $section = $phpWord->addSection(); // 简单文本：同时应用字体与段落样式 $section->addText('PHPWord Text Guide', 'titleFont', 'centerPara'); // 复杂段落：混排多种字体 $textrun = $section->addTextRun(['spaceAfter' => 200]); $textrun->addText('This is '); $textrun->addText('bold', ['bold' => true]); $textrun->addText(' and '); $textrun->addText('underlined', ['underline' => 'single']); $textrun->addText(' text in one paragraph.'); // 修订标记：插入一段文字 $text = $section->addText('Newly reviewed content.'); $text->setChangeInfo(TrackChange::INSERTED, 'Reviewer', new \DateTime()); // 写出为 Word 2007 文档 $writer = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'Word2007'); $writer->save('text-guide.docx');生成文档后可用 Word 或 LibreOffice 打开验证：第一段居中加粗标题、第二段内部混排样式、末段带修订插入标记。若需其他输出格式（HTML、ODText、RTF、PDF 等），可参阅 docs/usage/writers.md；若需从模板克隆行或替换变量，可参阅 docs/usage/template.md。
小结
- 简单段落选
addText，混排段落选addTextRun，二者的样式参数均可用命名样式名或内联数组，具体键值对照 字体样式 与 段落样式。 - 底层由 AbstractContainer.php 统一分派元素创建，
Text与TextRun元素分别定义在 Text.php 与 TextRun.php。 - 需要审阅修订时，使用
setChangeInfo()/setTrackChange()配合TrackChange::INSERTED/TrackChange::DELETED标记文字。 - 更多组合用法（列表、表格、页眉页脚、脚注等）可查阅 docs/usage/containers.md 与 samples 目录下的官方示例。
- 后端
【免费下载链接】PHPWord
A pure PHP library for reading and writing word processing documents
相关推荐
没有下载按钮的网页视频，用这个免费嗅探工具完整存下来
没有下载按钮的网页视频，用这个免费嗅探工具完整存下来 想把网页上的一集播客存进手机离线听？右键"另存为"只能存下一个网页，而播放按钮里藏着一个你拿不到的文件。装
后端macOS鼠标增强工具终极指南：5分钟让普通鼠标变身苹果触控板平替
macOS鼠标增强工具终极指南：5分钟让普通鼠标变身苹果触控板平替 滚轮一格一格跳得难受？侧键按下去毫无反应？中键在3D软件里拖不动视角？很多普通鼠标用户在切到
后端PHPWord实用技巧：文档生成与样式控制指南
PHPWord实用技巧：文档生成与样式控制指南 PHPWord作为一款强大的PHP文档处理库，能够帮助开发者轻松生成和操作Word文档。本文将介绍几个实用技巧，
后端
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
