告别乱码！PHPWord完美支持中文字体的3种实战方案
项目地址: https://gitcode.com/gh_mirrors/ph/PHPWord 你是否曾因PHPWord生成的文档中中文显示为方框或乱码而头疼？作为一款纯PHP的文档处理库（项目描述），PHPWord默认配置可能无法满足中文排版需求。本文将系统讲解如何通过全局配置、局部样式和模板替换三种方案，彻底解决中文字体显示问题，让你的文档呈现专业水准。
一、为什么中文字体总是显示异常？
PHPWord默认使用Arial字体（Settings.php），这是导致中文显示问题的核心原因。Windows系统常用的中文字体如"宋体"、"微软雅黑"等需要显式配置才能生效。
从架构设计看，字体配置通过PhpWord类提供的接口与Settings类交互，最终由XML writer组件写入文档属性。这种分层设计允许我们在不同层面控制字体行为。
二、方案一：全局默认字体配置（推荐）
通过修改全局设置，让所有文本默认使用中文字体，这是最简单高效的解决方案。PHPWord提供了两个关键配置项：
2.1 设置默认西文字体
$phpWord = new \PhpOffice\PhpWord\PhpWord();
$phpWord->setDefaultFontName('SimSun'); // 设置宋体为默认字体
2.2 针对亚洲语言的特殊配置
对于包含复杂脚本的中文文本，需单独设置亚洲字体：
$phpWord->setDefaultAsianFontName('Microsoft YaHei'); // 设置微软雅黑
这两个方法最终调用Settings类的静态方法：
// 核心实现代码
public static function setDefaultFontName(string $value): bool
{
if (trim($value) !== '') {
self::$defaultFontName = $value;
return true;
}
return false;
}
提示：全局配置会影响所有未指定字体的文本，适合整体风格统一的文档。完整API文档见PhpWord.php
三、方案二：局部文本样式定义
当文档需要多种字体混排时，可通过创建自定义样式实现精细化控制。这种方式优先级高于全局配置。
3.1 创建字体样式
// 添加字体样式
$phpWord->addFontStyle('ChineseStyle', [
'name' => 'SimHei', // 黑体
'size' => 12,
'color' => '000000'
]);
// 使用样式
$section = $phpWord->addSection();
$section->addText('这是黑体文本', 'ChineseStyle');
3.2 段落样式与字体组合
// 添加段落样式
$phpWord->addParagraphStyle('CenterParagraph', [
'alignment' => \PhpOffice\PhpWord\SimpleType\Jc::CENTER
]);
// 同时应用字体和段落样式
$section->addText('居中对齐的楷体文本', 'KaiTiStyle', 'CenterParagraph');
Style/Font.php定义了所有可用的字体属性，包括字重、斜体、下划线等高级设置。
四、方案三：模板替换中的字体指定
对于使用模板引擎生成文档的场景，需要在模板中预定义字体或通过PHP代码动态设置。
4.1 模板文件中直接设置字体
在Word模板文件中，预先将占位符文本的字体设置为中文字体，替换后文本将继承原有样式。
4.2 代码中动态应用样式
$templateProcessor = new \PhpOffice\PhpWord\TemplateProcessor('template.docx');
$templateProcessor->setComplexValue('content', [
'value' => '动态替换的文本',
'font' => 'SimSun',
'size' => 14
]);
注意：模板替换时需确保模板文件本身已包含所需中文字体定义。详细模板使用方法见template.md
五、常见问题与解决方案
5.1 字体名称对照表
不同系统下字体名称可能存在差异，建议使用跨平台字体名：
| 字体效果 | Windows名称 | Mac名称 | 代码设置 |
|---|---|---|---|
| 宋体 | SimSun | STSong | 'SimSun' |
| 黑体 | SimHei | STHeiti | 'SimHei' |
| 微软雅黑 | Microsoft YaHei | Microsoft YaHei | 'Microsoft YaHei' |
5.2 服务器字体安装检查
如果配置正确但仍显示异常，可能是服务器缺少对应字体文件：
# 检查Linux系统已安装字体
fc-list | grep "SimSun"
六、最佳实践总结
- 常规文档：使用全局配置
setDefaultFontName('SimSun') - 多语言文档：同时设置西文和亚洲字体
- 复杂排版：创建自定义样式并组合使用
- 模板文档：优先在模板中定义字体样式
通过本文介绍的方法，你可以彻底解决PHPWord中文显示问题。完整的API文档和更多示例可参考：
现在，开始创建专业的中文文档吧！如有其他问题，欢迎查阅FAQ或提交issue。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
