Itext7 HTML转PDF时Calibri Light字体无法正常切换问题

问题根因 #

iText pdfHTML 模块的字体匹配逻辑默认优先按「font-family名称 + 字重/样式」规则匹配同字族字体，你直接注册Calibri Light字体时没有添加对应font-family别名，HTML中写的'Calibri Light'/Calibri-Light无法被正确映射到加载的Light字重字体，就会 fallback 到同字族的普通Calibri（字重400）字体。

解决方案 #

根据你的场景可以二选一，也可以同时配置做兼容：

方案1：HTML层统一用字重区分（推荐） #

所有Calibri系列字体统一写font-family: 'Calibri'，靠font-weight属性区分字重：

• Calibri Light 对应font-weight: 300
• 常规Calibri 对应font-weight: 400
• Calibri Bold 对应font-weight: 700
• 斜体额外加font-style: italic即可

修改后的HTML示例：

<span style="font-size: 12pt; font-family: 'Calibri', sans-serif; font-weight: 300;">Calibri Light</span><br />
<span style="font-size: 12pt; font-family: 'Calibri', sans-serif; font-weight: 400;">Calibri</span>

方案2：后端给Calibri Light添加font-family别名 #

如果不能修改现有HTML代码，在注册字体时给Calibri Light添加对应的font-family别名，让iText能直接匹配到HTML中写的'Calibri Light'/Calibri-Light：
修改后的后端代码如下：

//Adding Calibri-Light and Calibri to the fonts
FontProvider fontProvider = new DefaultFontProvider(false, false, false);

FontProgram fontProgramCalibri = FontProgramFactory.CreateFont(Settings.DefaultBodyFont);
FontProgram fontProgramCalibriBold = FontProgramFactory.CreateFont(Settings.DefaultBoldFont);
FontProgram fontProgramCalibriLight = FontProgramFactory.CreateFont(Settings.DefaultHeadingFont);
FontProgram fontProgramCalibriItalics = FontProgramFactory.CreateFont(Settings.DefaultItalicsFont);

fontProvider.AddFont(fontProgramCalibri, PdfEncodings.WINANSI);
fontProvider.AddFont(fontProgramCalibriBold, PdfEncodings.WINANSI);
// 给Calibri Light添加别名，适配HTML中直接写Calibri Light/Calibri-Light的场景
fontProvider.AddFont(fontProgramCalibriLight, PdfEncodings.WINANSI, new List<string> { "Calibri Light", "Calibri-Light" });
fontProvider.AddFont(fontProgramCalibriItalics, PdfEncodings.WINANSI);

properties.SetFontProvider(fontProvider);

//Creating Body Text
HtmlConverter.ConvertToPdf(documentInstance.Text, pdfDocument, properties);

pdfDocument.Close();
document.Close();

return memoryStream.ToArray();

验证事项 #

确认配置项Settings.DefaultHeadingFont指向的是Calibri Light对应的字体文件（通常为calibril.ttf），避免字体文件本身加载错误。

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