企业官网建设流程全解析

• 后端

本篇技术指南围绕 PHPWord 中的 CheckBox（复选框）元素展开，讲解如何通过addCheckBox方法在文档节（Section）与表格单元格（Cell）中插入复选框、如何配置其字体与段落样式，并深入剖析 Word2007 与 ODText 两种写入器各自的底层实现差异。读完本文，你将能熟练地在 PHP 生成的 Word/ODF 文档中加入带名称、带可见标签的复选框表单控件。

一、核心 API：addCheckBox

在 PHPWord 中，CheckBox 元素可通过addCheckBox方法添加到节（Section）或表格单元格（Cell）中，该方法的完整签名如下（见 docs/usage/elements/checkbox.md）：

<?php $section->addCheckBox($name, $text, [$fontStyle], [$paragraphStyle]);

各参数含义：

addCheckBox由容器基类AbstractContainer以@method注解声明（src/PhpWord/Element/AbstractContainer.php）：

/** * @method CheckBox addCheckBox(string $name, $text, mixed $fStyle = null, mixed $pStyle = null) */

因为Section与Cell都继承自AbstractContainer，所以两者都能直接调用addCheckBox。

二、最小可用示例：节与表格单元格

仓库自带的示例 samples/Sample_22_CheckBox.php 完整演示了在节和表格单元格中插入复选框的两种方式，可直接运行或作为模板：

<?php include_once 'Sample_Header.php'; // 新建 PhpWord 对象 $phpWord = new PhpOffice\PhpWord\PhpWord(); // 新建节 $section = $phpWord->addSection(); // 在节中插入复选框 $section->addText('Check box in section'); $section->addCheckBox('chkBox1', 'Checkbox 1'); // 在表格单元格中插入复选框 $section->addText('Check box in table cell'); $table = $section->addTable(); $table->addRow(); $cell = $table->addCell(); $cell->addCheckBox('chkBox2', 'Checkbox 2'); // 保存文件 echo write($phpWord, basename(__FILE__, '.php'), $writers);

要点：

• addCheckBox与addText一样属于容器级方法，因此$section、$cell均可调用；
• 每个复选框应使用不同的$name，避免表单控件标识冲突；
• 示例末尾的write(...)来自Sample_Header.php，会按当前环境可用的写入器列表输出文档（如.docx、.odt等）。

三、样式配置：字体与段落

addCheckBox的第三个、第四个参数分别控制标签文本的字体样式与所在段落的段落样式，与普通文本元素完全一致。

3.1 字体样式$fontStyle

可通过样式配置数组设置，常用选项（完整列表见 docs/usage/styles/font.md）：

$section->addCheckBox( 'agree', 'I agree to the terms', [ 'bold' => true, 'italic' => true, 'size' => 12, 'name' => 'Arial', 'color' => 'FF0000', 'underline' => 'single', ] );

常用键及取值：

• bold/italic/smallCaps/allCaps/strikethrough/doubleStrikethrough/rtl/hidden：布尔值开关；
• size：字号，如20、22；
• name：字体名，如Arial；
• color：文字颜色，如FF0000；bgColor为背景色；fgColor为高亮色；
• underline：下划线类型，single、dash、dotted等，可参考\PhpOffice\PhpWord\Style\Font::UNDERLINE_...类常量；
• hint：字体内容类型，default、eastAsia或cs；
• lang：语言，如en-US、fr-BE；
• position：文字相对基线的位置，单位为半磅。

3.2 段落样式$paragraphStyle

用于控制复选框所在段落（如居中、缩进、段前段后间距），常用选项（完整列表见 docs/usage/styles/paragraph.md）：

$section->addCheckBox( 'agree', 'I agree to the terms', null, [ 'alignment' => 'center', 'spaceBefore' => 120, // twip 'spaceAfter' => 120, // twip 'keepNext' => true, ] );

常用键及取值：

• alignment：对齐方式，可取left、center、right、both等，参考\PhpOffice\PhpWord\SimpleType\Jc类常量；
• spaceBefore/spaceAfter：段前/段后间距，单位 twip（1 磅 = 20 twip）；
• indent/hanging：左缩进/悬挂缩进，单位为半英寸；
• lineHeight：行高，如1.0、1.5；
• keepNext、keepLines、widowControl、pageBreakBefore等分页控制开关；
• bidi：从右到左段落布局，布尔值。

3.3 样式对象的三种传参形式

$fontStyle与$paragraphStyle均支持三种传参方式：样式名称字符串、样式配置数组、以及样式对象（\PhpOffice\PhpWord\Style\Font/\PhpOffice\PhpWord\Style\Paragraph实例）。单元测试 tests/PhpWordTests/Element/CheckBoxTest.php 对这三种形式均有覆盖验证。

四、源码级实现：CheckBox 元素类

CheckBox元素类位于 src/PhpWord/Element/CheckBox.php，自 0.10.0 版本引入，其实现要点如下：

1. 继承自Text：复选框本质上是一个带表单控件语义的文本元素，构造函数在设置名称后调用父类Text的构造函数完成文本与样式初始化（L45-L49）：

public function __construct($name = null, $text = null, $fontStyle = null, $paragraphStyle = null) { $this->setName($name); parent::__construct($text, $fontStyle, $paragraphStyle); }

2. 名称统一转为 UTF-8：setName通过\PhpOffice\PhpWord\Shared\Text::toUTF8()对名称做编码归一化处理（L58-L63），避免多字节字符在输出时出现乱码。

3. 提供读取接口：通过getName()与继承自Text的getText()分别获取控件名称与可见标签，供各写入器在序列化时使用。

五、多格式写入原理：Word2007 与 ODText 的差异

复选框在不同输出格式中有着完全不同的底层表示，理解这一点有助于排查跨格式样式偏差问题。

5.1 Word2007（.docx）：基于域代码（Field Code）

Word2007 写入器将复选框渲染为 Word 表单域结构，见 src/PhpWord/Writer/Word2007/Element/CheckBox.php：

• 先写入w:fldChar（begin）并附带w:ffData表单域数据块，其中w:name记录控件名称、w:checkBox声明复选框类型且w:sizeAuto自动调整大小、w:default默认未勾选（值为 0）；
• 接着写入指令文本FORMCHECKBOX（w:instrText，保留空白）；
• 随后是separate与end两个w:fldChar边界；
• 最后单独用一个文本段（w:r+w:t）写入可见标签文本，并应用字体样式。

也就是说，在.docx中复选框是“域（field）+ 文本”的组合，勾选状态由 Word 客户端根据域内容动态呈现。

5.2 ODText（.odt）：原生 ODF 表单控件

ODText 写入器则将复选框输出为原生 ODF 表单控件（Form Control），这正是 docs/usage/elements/checkbox.md 结尾特别说明的行为：

当使用 ODText 写入器时，复选框被表示为原生 ODF 表单控件，并保留其名称与可见标签。

具体实现分为两层：

• 段落层：先以text:p段落写入可见标签文本，通过text:span应用字体样式，再写入一个draw:control锚点（draw:control属性值为control-{elementId}，draw:name为控件名称，字符串形式的字体样式会写入draw:text-style-name），见 src/PhpWord/Writer/ODText/Element/CheckBox.php 与基类 src/PhpWord/Writer/ODText/Element/Control.php；
• 表单层：在office:forms/form:form表单容器中生成form:checkbox元素，其中form:name保留控件名称、form:label保留可见标签、form:current-state初始为unchecked。

ODText 集成测试 tests/PhpWordTests/Writer/ODText/Element/FormControlsTest.php 精确断言了上述行为：form:checkbox的form:name为accept、form:label为Accept、初始状态为unchecked，且正文段落中存在对应的draw:control锚点。这意味着生成的.odt文件在 LibreOffice 等 ODF 应用中打开后，复选框是可交互的原生表单控件。

六、验证与测试

仓库为 CheckBox 提供了完善的单元测试与集成测试：

• 元素层测试tests/PhpWordTests/Element/CheckBoxTest.php：验证无参构造时的默认样式对象、名称与文本的读写、字体/段落样式数组与对象两种传参方式的转换；
• ODText 集成测试tests/PhpWordTests/Writer/ODText/Element/FormControlsTest.php：验证原生表单控件 XML 结构及名称、标签、勾选状态属性。

如需自行验证输出效果，可运行示例：

php samples/Sample_22_CheckBox.php

生成的文件中应分别包含名为chkBox1（节内）与chkBox2（表格单元格内）的复选框控件。

七、注意事项

• $name是控件的唯一标识，在同一文档内尽量保持唯一，避免 Word/ODF 表单处理时发生冲突；
• 复选框默认状态为未勾选（Word2007 的w:default为 0，ODF 的form:current-state为unchecked）；若需要初始勾选等更复杂行为，可考虑结合FormField元素（addFormField('checkbox')，见 src/PhpWord/Element/AbstractContainer.php）与文档保护设置配合使用；
• 在.docx中复选框以“域”形式呈现，勾选交互依赖 Word 客户端；在.odt中则是原生表单控件，两者在纯文本预览或转换场景下的表现可能不同。

• 后端