字体扩展

目录

• 概述
• 适用场景
• 扩展机制（SPI）
• FontRegister 接口
• 参考实现
• 已内置的扩展字体
• 使用步骤
• 与"特殊字体扩展"的关系

概述

报表设计器默认仅提供几种常见字体。当报表需要使用额外的字体（如企业指定的中文字体、商业字体或非系统默认字体）时，可以通过字体扩展机制把字体库（.ttf / .ttc 文件）注册到报表引擎中，从而在单元格样式里选择并使用这些字体。

适用场景

• 默认字体列表不满足报表设计需求，需要补充特定字体；
• 需要在 PDF 等导出中保持与设计一致的字体呈现（字体库随报表一起加载，避免导出环境缺少该字体而回退为默认字体）。

注意：字体扩展主要影响 PDF 导出（字体库被内嵌到 PDF 中）。Web 预览、Excel、Word、CSV 等导出取决于运行/查看环境的字体可用性，并不依赖此处注册的字体库。

扩展机制（SPI）

字体扩展基于 Java 的 SPI（Service Provider Interface） 机制实现：只要在项目 classpath 下提供 FontRegister 接口的实现，并在 META-INF/services 中登记，报表引擎在启动时就会自动加载并注册该字体。

详见 【SPI 集成说明】。

FontRegister 接口

扩展字体需要实现的接口如下：

package com.basksoft.report.core.export.pdf.font;

public interface FontRegister {
    /**
     * @return 返回自定义的字体名称
     */
    String getFontName();
    /**
     * 返回字体所在位置，需要注意的是字体文件需要放置到classpath下，这里返回的值就是该字体文件所在classpath下位置即可
     * @return 返回字体所在位置
     */
    String getFontPath();
}

• getFontName()：返回字体在报表中显示和选用的名称（如 "黑体"）；
• getFontPath()：返回字体库文件在 classpath 下的相对路径（如 com/basksoft/report/font/heiti/SIMHEI.TTF），引擎据此加载字体库。

参考实现

下面以"黑体"为例，演示如何注册一个 TTF 字体：

public class HeiTiFontRegister implements FontRegister {

    public String getFontName() {
        return "黑体";
    }

    public String getFontPath() {
        return "com/basksoft/report/font/heiti/SIMHEI.TTF";
    }
}

其中 getFontName 用于返回字体的名称，getFontPath 用于告诉报表引擎加载字体库的位置。TTF 文件即为对应的字体库文件（也支持 .ttc 字体集合文件）。

配套还需要在 META-INF/services/com.basksoft.report.core.export.pdf.font.FontRegister 文件中登记实现类的全限定名：

com.basksoft.report.font.heiti.HeiTiFontRegister

已内置的扩展字体

报表已通过 SPI 内置注册了以下字体，开箱即可在单元格样式中选择使用：

如需新增字体，按上文"参考实现"添加自己的 FontRegister 实现并登记即可。

使用步骤

1. 准备字体库文件（.ttf / .ttc），放入项目的 classpath 目录（如 src/main/resources/com/xxx/report/font/...）；
2. 实现 FontRegister 接口，在 getFontName 返回字体名称、getFontPath 返回该字体库在 classpath 下的路径；
3. 在 META-INF/services/com.basksoft.report.core.export.pdf.font.FontRegister 中登记实现类的全限定名；
4. 启动报表服务，字体即出现在单元格字体下拉列表中，可直接选用。

与"特殊字体扩展"的关系

FontRegister 适用于"把字体库注册进来正常使用"的普通场景。如果某些字体（如高棉语 Khmer OS）直接输出到 PDF 后显示不正常，需要对其文本做字节码转换或指定最终渲染字体，则需使用更高级的 FontRenderRegister 扩展，详见 特殊字体扩展。