后端【免费下载链接】PHPWordA pure PHP library for reading and writing word processing documents项目地址https://gitcode.com/gh_mirrors/ph/PHPWord点击查看免费下载PHPWord 1.0.02022-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 CHANGEMost 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 只移除了一个类原类替代方案PhpOffice\PhpWord\TemplatePhpOffice\PhpWord\TemplateProcessorTemplate是 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.0.0 替代方案当前源码UNDERLINE_DOTHASH、UNDERLINE_DOTHASHHEAVYStyle\FontFont::UNDERLINE_DOTDASHdotDash、Font::UNDERLINE_DOTDASHHEAVYdotDashHeavy见 Font.phpVALIGN_TOP、VALIGN_CENTER、VALIGN_BOTTOM、VALIGN_BOTHStyle\CellSimpleType\VerticalJc枚举类见 VerticalJc.phpTABLEADER_DOT、TABLEADER_UNDERSCORE、TABLEADER_LINE、TABLEADER_NONEStyle\TOCStyle\Tab的TAB_LEADER_*常量none/dot/hyphen/underscore/heavy/middleDot配合setTabLeader()使用见 Tab.php 与 TOC.phpWIDTH_AUTO、WIDTH_PERCENT、WIDTH_TWIPStyle\TableSimpleType\TblWidth枚举NILnil、AUTOauto、PERCENTpct、TWIPdxa见 TblWidth.phpDEFAULT_FONT_NAME、DEFAULT_FONT_SIZE、DEFAULT_FONT_COLOR、DEFAULT_FONT_CONTENT_TYPEPhpWordSettings::get/setDefaultFontName()、get/setDefaultFontSize()、get/setDefaultFontColor()见 Settings.php几个关键迁移细节1字体下划线样式。原UNDERLINE_DOTHASH/UNDERLINE_DOTHASHHEAVY在 Font.php 中已不存在取而代之的是拼写更规范的UNDERLINE_DOTDASHdotDash与UNDERLINE_DOTDASHHEAVYdotDashHeavy。升级时注意是下划线命名规则的调整不要机械替换为同名常量。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\FootnotePropertiessetFootnoteProperties(?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.phpMedia::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()。旧 API1.0.0 替代loadTemplate($file)直接使用new TemplateProcessor($file)createSection($settings)addSection($style null)。旧方法源码中曾保留并直接委托给addSection()见 PhpWord.php1.0.0 起彻底删除getDocumentProperties()/setDocumentProperties()getDocInfo()见 PhpWord.phpgetProtection()文档保护信息收敛至Metadata\ProtectionProtection.php通过设置层配置// 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 中被移除1.0.0 替代Font::getBold()Font::isBold()Font::getItalic()Font::isItalic()Font::getSuperScript()Font::isSuperScript()Font::getSubScript()Font::isSubScript()Font::getStrikethrough()Font::isStrikethrough()返回?boolFont::getParagraphStyle()段样式作为独立参数传给addText($text, $fontStyle, $paragraphStyle)等容器方法规律二对齐、分页、行高等样式属性改为样式数组键配置。被移除的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\JcJc.php含START/END/BOTH旧的LEFT/RIGHT/CENTER自 0.13.0 起即被标记弃用与SimpleType\JcTableJcTable.php行距规则使用SimpleType\LineSpacingRuleLineSpacingRule.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 border1这类属性现在能正确映射为表格边框样式HTML Reader段落级page-break-after样式支持导入 HTML 时p stylepage-break-after: always可正确生成分页符HTML ReaderText 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。升级实操清单全局搜索旧符号在代码库中检索上文中被移除的类名Template、常量UNDERLINE_DOTHASH、VALIGN_*、TABLEADER_*、WIDTH_*、DEFAULT_FONT_*与方法名createTextRun、createSection、loadTemplate、getDocumentProperties、getFootnotePropoperties等逐一确认命中位置按上表替换常量类替换为对应枚举TblWidth、VerticalJc、Tab::TAB_LEADER_*、Font::UNDERLINE_DOTDASH等方法类替换为add*/is*前缀或样式数组键写法验证模板代码凡涉及Template的地方确认已改用 TemplateProcessor运行测试composer test执行仓库单元测试同时以 Sample_03_Sections.php、Sample_04_Textrun.php、Sample_12_HeaderFooter.php 等示例为回归基准对文档生成输出做抽样比对确认运行环境将 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.01.5.0 的演进记录可继续在 docs/changes/1.x 目录中追踪。赞分享后端【免费下载链接】PHPWordA pure PHP library for reading and writing word processing documents项目地址https://gitcode.com/gh_mirrors/ph/PHPWord点击查看免费下载相关推荐Pydantic V2 迁移完全指南从 V1 升级的破坏性变更、API 对照与实战迁移方案Pydantic V2 迁移完全指南从 V1 升级的破坏性变更、API 对照与实战迁移方案 Pydantic V2 在保留“基于 Python 类型注解做数据后端序列化libuv 0.10 到 1.0.0 升级迁移指南API 变更全景解析与实战改造对照libuv 0.10 到 1.0.0 升级迁移指南API 变更全景解析与实战改造对照 导读 libuv 1.0.0 在 0.10 发布之后经历了大规模 API网络通信异步编程AngularJS Material v1.2 升级迁移指南破坏性变更详解与实战对照AngularJS Material v1.2 升级迁移指南破坏性变更详解与实战对照 AngularJS MaterialMaterial Design fUI组件前端上一篇【亲测免费】 探索大脑的奥秘Nilearn——神经影像分析的利器下一篇lwIP 项目教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/28 2:22:25 · 阅读 1.2k PHPWord 1.0.0 升级迁移指南：破坏性变更全解析与替代 API 对照
后端【免费下载链接】PHPWordA pure PHP library for reading and writing word processing documents项目地址https://gitcode.com/gh_mirrors/ph/PHPWord点击查看免费下载PHPWord 1.0.02022-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 CHANGEMost 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 只移除了一个类原类替代方案PhpOffice\PhpWord\TemplatePhpOffice\PhpWord\TemplateProcessorTemplate是 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.0.0 替代方案当前源码UNDERLINE_DOTHASH、UNDERLINE_DOTHASHHEAVYStyle\FontFont::UNDERLINE_DOTDASHdotDash、Font::UNDERLINE_DOTDASHHEAVYdotDashHeavy见 Font.phpVALIGN_TOP、VALIGN_CENTER、VALIGN_BOTTOM、VALIGN_BOTHStyle\CellSimpleType\VerticalJc枚举类见 VerticalJc.phpTABLEADER_DOT、TABLEADER_UNDERSCORE、TABLEADER_LINE、TABLEADER_NONEStyle\TOCStyle\Tab的TAB_LEADER_*常量none/dot/hyphen/underscore/heavy/middleDot配合setTabLeader()使用见 Tab.php 与 TOC.phpWIDTH_AUTO、WIDTH_PERCENT、WIDTH_TWIPStyle\TableSimpleType\TblWidth枚举NILnil、AUTOauto、PERCENTpct、TWIPdxa见 TblWidth.phpDEFAULT_FONT_NAME、DEFAULT_FONT_SIZE、DEFAULT_FONT_COLOR、DEFAULT_FONT_CONTENT_TYPEPhpWordSettings::get/setDefaultFontName()、get/setDefaultFontSize()、get/setDefaultFontColor()见 Settings.php几个关键迁移细节1字体下划线样式。原UNDERLINE_DOTHASH/UNDERLINE_DOTHASHHEAVY在 Font.php 中已不存在取而代之的是拼写更规范的UNDERLINE_DOTDASHdotDash与UNDERLINE_DOTDASHHEAVYdotDashHeavy。升级时注意是下划线命名规则的调整不要机械替换为同名常量。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\FootnotePropertiessetFootnoteProperties(?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.phpMedia::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()。旧 API1.0.0 替代loadTemplate($file)直接使用new TemplateProcessor($file)createSection($settings)addSection($style null)。旧方法源码中曾保留并直接委托给addSection()见 PhpWord.php1.0.0 起彻底删除getDocumentProperties()/setDocumentProperties()getDocInfo()见 PhpWord.phpgetProtection()文档保护信息收敛至Metadata\ProtectionProtection.php通过设置层配置// 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 中被移除1.0.0 替代Font::getBold()Font::isBold()Font::getItalic()Font::isItalic()Font::getSuperScript()Font::isSuperScript()Font::getSubScript()Font::isSubScript()Font::getStrikethrough()Font::isStrikethrough()返回?boolFont::getParagraphStyle()段样式作为独立参数传给addText($text, $fontStyle, $paragraphStyle)等容器方法规律二对齐、分页、行高等样式属性改为样式数组键配置。被移除的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\JcJc.php含START/END/BOTH旧的LEFT/RIGHT/CENTER自 0.13.0 起即被标记弃用与SimpleType\JcTableJcTable.php行距规则使用SimpleType\LineSpacingRuleLineSpacingRule.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 border1这类属性现在能正确映射为表格边框样式HTML Reader段落级page-break-after样式支持导入 HTML 时p stylepage-break-after: always可正确生成分页符HTML ReaderText 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。升级实操清单全局搜索旧符号在代码库中检索上文中被移除的类名Template、常量UNDERLINE_DOTHASH、VALIGN_*、TABLEADER_*、WIDTH_*、DEFAULT_FONT_*与方法名createTextRun、createSection、loadTemplate、getDocumentProperties、getFootnotePropoperties等逐一确认命中位置按上表替换常量类替换为对应枚举TblWidth、VerticalJc、Tab::TAB_LEADER_*、Font::UNDERLINE_DOTDASH等方法类替换为add*/is*前缀或样式数组键写法验证模板代码凡涉及Template的地方确认已改用 TemplateProcessor运行测试composer test执行仓库单元测试同时以 Sample_03_Sections.php、Sample_04_Textrun.php、Sample_12_HeaderFooter.php 等示例为回归基准对文档生成输出做抽样比对确认运行环境将 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.01.5.0 的演进记录可继续在 docs/changes/1.x 目录中追踪。赞分享后端【免费下载链接】PHPWordA pure PHP library for reading and writing word processing documents项目地址https://gitcode.com/gh_mirrors/ph/PHPWord点击查看免费下载相关推荐Pydantic V2 迁移完全指南从 V1 升级的破坏性变更、API 对照与实战迁移方案Pydantic V2 迁移完全指南从 V1 升级的破坏性变更、API 对照与实战迁移方案 Pydantic V2 在保留“基于 Python 类型注解做数据后端序列化libuv 0.10 到 1.0.0 升级迁移指南API 变更全景解析与实战改造对照libuv 0.10 到 1.0.0 升级迁移指南API 变更全景解析与实战改造对照 导读 libuv 1.0.0 在 0.10 发布之后经历了大规模 API网络通信异步编程AngularJS Material v1.2 升级迁移指南破坏性变更详解与实战对照AngularJS Material v1.2 升级迁移指南破坏性变更详解与实战对照 AngularJS MaterialMaterial Design fUI组件前端上一篇【亲测免费】 探索大脑的奥秘Nilearn——神经影像分析的利器下一篇lwIP 项目教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考