使用TemplateProcessor时如何将HTML转换为OOXML？

我之前在项目里刚好遇到过一模一样的需求——用TemplateProcessor处理docx模板时插入HTML内容，确实Html::addHtml和TemplateProcessor不能直接配合，不过我们可以绕个弯子实现，核心思路是先把HTML转换成PhpWord可识别的元素，提取对应的OOXML片段，再替换模板里的占位符。

具体实现步骤 #

1. 创建临时的PhpWord实例和Section，用Html::addHtml把HTML内容转换为Section里的文档元素
2. 从临时Section中提取生成的OOXML代码
3. 使用TemplateProcessor的复杂值替换方法，把OOXML片段插入到模板的指定位置

完整代码示例 #

use PhpOffice\PhpWord\PhpWord;
use PhpOffice\PhpWord\Shared\Html;
use PhpOffice\PhpWord\TemplateProcessor;
use PhpOffice\PhpWord\IOFactory;

// 1. 准备需要插入的HTML内容
$htmlContent = '<div>
    <p>这是一段<b>加粗</b>的文本，还有<i>斜体</i>效果。</p>
    <ul>
        <li>列表项1</li>
        <li>列表项2</li>
    </ul>
    <p>这是另一个段落，包含<a href="#">链接</a>。</p>
</div>';

// 2. 创建临时PhpWord实例，将HTML转换为文档元素
$tempPhpWord = new PhpWord();
$tempSection = $tempPhpWord->addSection();
// 第三个参数设为false表示不使用默认样式，第四个参数设为false表示不添加额外段落标记
Html::addHtml($tempSection, $htmlContent, false, false);

// 3. 提取转换后的OOXML片段
$tempWriter = IOFactory::createWriter($tempPhpWord, 'Word2007');
$tempDocument = $tempWriter->getDocument();

// 使用XPath获取body下的所有内容节点（适配多段落、列表等复杂HTML）
$xpath = new \DOMXPath($tempDocument);
$nodes = $xpath->query('/w:document/w:body/*');
$ooxmlContent = '';
foreach ($nodes as $node) {
    $ooxmlContent .= $node->C14N();
}

// 4. 处理模板并插入OOXML
$templateProcessor = new TemplateProcessor('your-template-file.docx');

// 假设模板中的占位符是 ${html_content}
// 先清空占位符的默认文本（避免残留内容）
$templateProcessor->setValue('html_content', '', '');
// 使用setComplexValue插入OOXML片段
$templateProcessor->setComplexValue('html_content', $ooxmlContent, 'html');

// 5. 保存处理后的文档
$templateProcessor->saveAs('final-output.docx');

关键注意事项 #

• XPath节点选择：如果你的HTML生成了多种元素（段落、列表、表格等），一定要用合适的XPath来获取所有需要的节点，比如/w:document/w:body/*可以获取body下的所有子元素，避免遗漏内容。
• 样式兼容：HTML的样式可能和模板的默认样式冲突，你可以在addHtml时传入自定义样式数组，或者提前调整模板的样式，确保插入的内容和模板风格统一。
• 特殊内容处理：如果HTML包含图片，需要确保图片路径是PhpWord可访问的（可以用绝对路径），并且Html::addHtml能正确解析图片标签；如果有复杂表格，可能需要额外调试OOXML的结构。
• setComplexValue参数：第三个参数传入'html'是告诉PhpWord按照HTML对应的OOXML格式处理片段，如果你直接传入完整的OOXML节点，也可以省略这个参数。

内容的提问来源于stack exchange，提问作者Richard