企业官网建设流程全解析

• 后端

PHPWord 1.0.0（2022-11-15 发布）是 0.18.3 之后的首个 1.0 正式版本，其核心动作是"清理历史包袱"：将所有在 0.x 时代被标记为废弃（deprecated）的类、常量与方法一次性移除，同时完成 PHP 8.1 兼容性修复、HTML Reader 的多项行为修正，并正式放弃 PHP 7.0 及更早版本的支持。本文以仓库内 1.0.0 变更说明 为骨架，结合当前源码逐一列出被移除的 API 清单、给出经源码验证的替代方案与迁移前后代码示例，帮助从 0.18.x 及更早版本升级上来的开发者一次性完成"查漏 → 替换 → 验证"的迁移闭环。

版本背景：从 0.18.3 到 1.0.0 的升级主线

官方变更说明在开篇即点明了 1.0.0 的升级主基调：

BREAKING CHANGE：Most deprecated things were dropped.（绝大多数废弃内容已被移除）

也就是说，1.0.0 不是一次功能大爆发，而是一次"技术债清算"。从 0.7.0 到 0.18.3 期间陆续标记为废弃的旧 API（例如createSection()、loadTemplate()、getDocumentProperties()等）在本次版本中被彻底删除。仓库 docs/changes/0.x 目录下的各版本说明记录了这些 API 从引入到弃用的完整历史，docs/changes/1.x 目录则承载 1.x 时代的新变更。

配合本次清理，1.0.0 还包含两个值得注意的改动：

• 放弃 PHP 7.0 及更早版本（见下方"版本与平台要求"小节）；
• 一批 Bug 修复，其中多项集中在 HTML Reader 上（见"1.0.0 修复要点"小节）。

被移除的类：Template正式退役

1.0.0 只移除了一个类：

Template是 0.x 早期基于占位符替换的模板处理类，随着 TemplateProcessor 的成熟（支持 cloneRow、cloneBlock、setValue、setChart 等能力）而被取代。升级时只需将类名与构造方式替换即可：

// 0.18.x 及更早 $template = new \PhpOffice\PhpWord\Template('template.docx'); // 1.0.0 $templateProcessor = new \PhpOffice\PhpWord\TemplateProcessor('template.docx'); $templateProcessor->setValue('name', 'PHPWord'); $templateProcessor->saveAs('output.docx');

仓库中 Sample_07_TemplateCloneRow.php、Sample_23_TemplateBlock.php、Sample_40_TemplateSetComplexValue.php 等示例以及 TemplateProcessorTest.php 测试均可作为新 API 的权威用法参考。

被移除的常量：全部收敛为枚举类或 Settings 配置

1.0.0 共移除 5 组常量，替代方案全部指向当前仓库中仍在使用的枚举类或全局配置，见下表：

几个关键迁移细节：

1）字体下划线样式。原UNDERLINE_DOTHASH/UNDERLINE_DOTHASHHEAVY在 Font.php 中已不存在，取而代之的是拼写更规范的UNDERLINE_DOTDASH（'dotDash'）与UNDERLINE_DOTDASHHEAVY（'dotDashHeavy'）。升级时注意是"下划线命名规则"的调整，不要机械替换为同名常量。

2）表格宽度单位。原Table::WIDTH_*常量迁移至 TblWidth.php 枚举后，宽度单位值改为 OOXML 标准字符串（'auto'/'pct'/'dxa'）。设置表格宽度时应配合unit键使用：

// 1.0.0 推荐写法 $tableStyle = [ 'width' => 5000, 'unit' => \PhpOffice\PhpWord\SimpleType\TblWidth::TWIP, // 'dxa' ]; $section->addTable($tableStyle);

3）默认字体。全局默认字体的常量被移除后，统一改由 Settings.php 的静态方法管理；同时 PhpWord.php 保留了setDefaultFontName()、setDefaultFontSize()、setDefaultFontColor()等顶层代理方法，多数业务代码无需改动：

$phpWord->setDefaultFontName('Noto Serif SC'); $phpWord->setDefaultFontSize(10.5); // 注意：自 1.1.0 起支持小数号字号 $phpWord->setDefaultFontColor('333333');

4）单元格垂直对齐与 TOC 制表符。原Cell::VALIGN_*请改用SimpleType\VerticalJc枚举；原TOC::TABLEADER_*已随 TOC.php 改为继承Tab样式体系（构造函数默认TAB_STOP_RIGHT+ 9062 twip +TAB_LEADER_DOT），目录样式的制表符前导符通过setTabLeader()设置。

被移除的方法：六大类别的迁移对照

1.0.0 移除了近 60 个方法，按职责可归为六类。下面逐类给出"旧调用 → 新调用"的迁移对照，所有替代 API 均已在当前源码中确认存在。

类别一：容器与元素创建方法（AbstractContainer）

被移除：AbstractContainer::createTextRun()、createFootnote()，以及Footnote::getReferenceId()/setReferenceId()、Image::getIsWatermark()/getIsMemImage()、Link::getTarget()/getLinkSrc()/getLinkName()、OLEObject::getObjectId()/setObjectId()。

迁移说明：文本与脚注的创建统一走 AbstractContainer.php 的魔法方法__call()（见 L87-L120），该类 docblock 中@method声明的addTextRun()、addFootnote()、addLink()、addOLEObject()、addImage()即为 1.0.0 的正式入口：

// 0.18.x 及更早 $section->createTextRun(); $section->createFootnote(); // 1.0.0 $section->addTextRun(); $section->addFootnote(); $section->addLink('https://example.com', '链接文本'); $section->addOLEObject('data.xls'); // addObject() 也已在内部映射为 OLEObject $section->addImage('logo.png', $style); // 水印能力通过 addImage 的 $isWatermark 参数表达

脚注的引用 ID 不再由用户手动读写，改由PhpWord的脚注集合（getFootnotes()）统一管理，见 PhpWord.php 的集合机制。

类别二：Section的页眉页脚与脚注属性

被移除：Section::createHeader()/createFooter()/getFooter()/getFootnotePropoperties()/setSettings()/getSettings()。

迁移对照（见 Section.php）：

// 0.18.x 及更早 $section->createHeader(); $section->createFooter(); $footer = $section->getFooter(); $props = $section->getFootnotePropoperties(); // 注意原拼写错误 // 1.0.0 $header = $section->addHeader(); // 默认 Header::AUTO $footer = $section->addFooter(); $allFooters = $section->getFooters(); // 返回 Footer[] $props = $section->getFootnoteProperties(); // 拼写修正 $section->setFootnoteProperties($props);

其中getFootnoteProperties()返回PhpOffice\PhpWord\ComplexType\FootnoteProperties，setFootnoteProperties(?FootnoteProperties)接受该类型或null。完整页眉页脚写法可参考 Sample_12_HeaderFooter.php。

类别三：Media静态 API 收敛

被移除：Media::addSectionMediaElement()/addSectionLinkElement()/getSectionMediaElements()/countSectionMediaElements()/addHeaderMediaElement()/countHeaderMediaElements()/getHeaderMediaElements()/addFooterMediaElement()/countFooterMediaElements()/getFooterMediaElements()。

迁移说明：0.x 按"节/页眉/页脚"维度拆分了一堆媒体管理方法；1.0.0 统一收敛为以容器为第一参数的三个方法，见 Media.php：

• Media::addElement($container, $mediaType, $source, ?Image $image = null)
• Media::countElements($container, $mediaType = null)
• Media::getElements($container, $type = null)

对于业务代码而言，媒体元素的增删查已由Section::addImage()等容器方法内部完成，绝大多数场景无需直接调用Media静态方法。

类别四：PhpWord顶层 API

被移除：PhpWord::getProtection()/loadTemplate()/createSection()/getDocumentProperties()/setDocumentProperties()。

// 1.0.0 $phpWord = new \PhpOffice\PhpWord\PhpWord(); $section = $phpWord->addSection(['orientation' => 'landscape']); $docInfo = $phpWord->getDocInfo(); $docInfo->setTitle('My Document')->setCreator('PHPWord');

类别五：样式访问器收敛为"is 前缀"与样式数组键

这是改动面最大的一组，包括Font、Paragraph、Frame、NumberingLevel、Row、Spacing、Table的多个 getter/setter。迁移规律有二：

规律一：布尔属性 getter 改为is*前缀。例如 Font.php 中：

规律二：对齐、分页、行高等样式属性改为"样式数组键"配置。被移除的Paragraph::getAlign()/setAlign()、Frame::getAlign()/setAlign()、NumberingLevel::getAlign()/setAlign()、Table::getAlign()/setAlign()、Paragraph::getWidowControl()/getKeepNext()/getKeepLines()/getPageBreakBefore()、Row::getTblHeader()/isTblHeader()/getCantSplit()/getExactHeight()、Spacing::getRule()/setRule()等，统一回归"用数组定义样式"的声明式写法：

$paragraphStyle = [ 'alignment' => \PhpOffice\PhpWord\SimpleType\Jc::START, // 见 SimpleType\Jc 'keepNext' => true, 'keepLines' => true, 'pageBreakBefore'=> true, 'widowControl' => false, ]; $rowStyle = [ 'tblHeader' => true, // 跨页重复表头 'cantSplit' => true, // 禁止行内分页 'exactHeight'=> 300, ]; $tableStyle = [ 'alignment' => \PhpOffice\PhpWord\SimpleType\JcTable::CENTER, // 见 SimpleType\JcTable ];

对齐取值请参考SimpleType\Jc（Jc.php，含START/END/BOTH，旧的LEFT/RIGHT/CENTER自 0.13.0 起即被标记弃用）与SimpleType\JcTable（JcTable.php）；行距规则使用SimpleType\LineSpacingRule（LineSpacingRule.php）。同时注意：

• Style\AbstractStyle::setArrayStyle()被移除——样式数组现在直接通过AbstractStyle的属性映射机制生效，不再需要显式调用该方法。
• Style\Cell::getDefaultBorderColor()被移除——边框颜色改由样式数组的borderColor等键配置。
• Writer\AbstractWriter::getUseDiskCaching()改名为isUseDiskCaching()，setUseDiskCaching($value, $directory)保留，见 AbstractWriter.php。

类别六：Reader / Writer 基础设施

被移除：Reader\AbstractReader::getReadDataOnly()、Settings::getCompatibility()、Writer\HTML::writeDocument()。

• 读取"仅数据"开关的 getter 改为isReadDataOnly()（默认true），配套setReadDataOnly($value)，见 AbstractReader.php。1.1.0 后还新增了setImageLoading()开关（AbstractReader.php）。
• 兼容性配置不再从Settings读取，改为从PhpWord实例获取：$phpWord->getCompatibility()返回Metadata\Compatibility（见 PhpWord.php）。
• Writer\HTML::writeDocument()删除后，HTML 输出统一走PhpWord::save($filename, 'HTML')或IOFactory::createWriter($phpWord, 'HTML')的标准保存流程。

1.0.0 修复要点

除移除废弃 API 外，1.0.0 还修复了一批问题，其中多项与 HTML 读取相关：

• Multiple PHP 8.1 fixes：修复 PHP 8.1 环境下的一批兼容性缺陷（如 null 相关弃用警告、内部 API 行为变化等），是本次升级对运行环境最重要的一项保障；
• loadConfig返回实际生效的配置：此前AbstractReader::loadConfig()的返回值可能与实际应用结果不一致，1.0.0 保证返回值为真正应用后的配置；
• HTML Reader：表格内联样式覆盖 HTML 属性：当<table>同时存在内联style与width/border等 HTML 属性时，内联样式优先；
• HTML Reader：使用border属性解析表格边框：<table border="1">这类属性现在能正确映射为表格边框样式；
• HTML Reader：段落级page-break-after样式支持：导入 HTML 时<p style="page-break-after: always">可正确生成分页符；
• HTML Reader：Text Run 中不允许出现标题：<h1>等标题标签嵌入文本运行（Text Run）内部时不再被错误接受，行为与 OOXML 语义一致。

上述修复对应的解析逻辑集中在 HTML.php，相关回归验证见 HTMLTest.php。

版本与平台要求

变更说明的 Miscellaneous 部分明确：1.0.0 起放弃对 PHP 7.0 及更早版本的支持。当前仓库 composer.json 中的约束为：

"require": { "php": "^7.1|^8.0", "ext-dom": "*", "ext-zip": "*", "ext-json": "*", "ext-xml": "*", "phpoffice/common": "^1.1", "phpoffice/math": "^0.3" }

即升级到 1.0.0 的最低前提是PHP 7.1+（含 8.x），并需要ext-dom、ext-zip、ext-json、ext-xml扩展。若当前项目仍运行在 PHP 7.0 上，请先升级 PHP 运行时。官方安装方式（Composer）详见 docs/install.md。

升级实操清单

1. 全局搜索旧符号：在代码库中检索上文中被移除的类名（Template）、常量（UNDERLINE_DOTHASH、VALIGN_*、TABLEADER_*、WIDTH_*、DEFAULT_FONT_*）与方法名（createTextRun、createSection、loadTemplate、getDocumentProperties、getFootnotePropoperties等），逐一确认命中位置；
2. 按上表替换：常量类替换为对应枚举（TblWidth、VerticalJc、Tab::TAB_LEADER_*、Font::UNDERLINE_DOTDASH等）；方法类替换为add*/is*前缀或样式数组键写法；
3. 验证模板代码：凡涉及Template的地方确认已改用 TemplateProcessor；
4. 运行测试：composer test执行仓库单元测试；同时以 Sample_03_Sections.php、Sample_04_Textrun.php、Sample_12_HeaderFooter.php 等示例为回归基准，对文档生成输出做抽样比对；
5. 确认运行环境：将 PHP 版本提升至 7.1+ 并确保所需扩展齐全（见上文composer.json）。

小结

PHPWord 1.0.0 是一次以"删除"为主题的里程碑发布：Template类退役、5 组常量与近 60 个方法被移除，同时配以 PHP 8.1 修复与 HTML Reader 行为修正。迁移的核心规律可以概括为三句话：类层面从Template走向TemplateProcessor；常量层面从"裸常量"走向SimpleType枚举类；方法层面从create*/get*走向add*/is*与声明式样式数组。掌握这三条规律，再配合本文的逐项对照表，即可快速完成从 0.x 到 1.0.0 的平滑升级。后续 1.1.0～1.5.0 的演进记录可继续在 docs/changes/1.x 目录中追踪。

• 后端