TECNOLOGIA X - Jasper - Utilização de fontes personalizados no JasperReports – Senior

Este artigo contém os seguintes tópicos:

A plataforma Senior X suporta fontes personalizadas no JasperReports
Inclusão da fonte
É necessário instalar a fonte no servidor
Pontos de atenção

A plataforma Senior X suporta fontes personalizadas no JasperReports?

Sim. O mecanismo de relatórios utiliza o recurso Font Extensions do JasperReports, que permite registrar famílias de fontes personalizadas para utilização nos relatórios.

Esse mecanismo também é utilizado para disponibilizar fontes como Arial, Courier New, Times New Roman, Georgia, Trebuchet, Verdana e Impact, conforme as extensões de fontes configuradas no ambiente.

Para utilizar uma fonte personalizada, é possível empacotar uma extensão de fontes em um arquivo JAR e incluí-la no pacote ZIP do relatório, desde que esse procedimento seja compatível com a implementação da plataforma.

Inclusão da fonte

O procedimento consiste em criar uma extensão de fontes do JasperReports, incluir os arquivos necessários no JAR e adicionar esse arquivo ao pacote ZIP do relatório.

1. Preparar os arquivos da fonte

Obtenha os arquivos da família de fontes necessários para os estilos utilizados no relatório.

Exemplo de estrutura do arquivo fonts.jar:

fonts.jar
├── jasperreports_extension.properties
├── fonts.xml
└── fonts/
    ├── Regular.ttf
    ├── Bold.ttf
    ├── Italic.ttf
    └── BoldItalic.ttf

Os nomes dos arquivos e os caminhos declarados nos arquivos de configuração devem corresponder exatamente à estrutura interna do JAR.

2. Configurar o registro da extensão

Crie o arquivo jasperreports_extension.properties com o seguinte conteúdo:

net.sf.jasperreports.extension.registry.factory.fonts=net.sf.jasperreports.engine.fonts.SimpleFontExtensionsRegistryFactory
net.sf.jasperreports.extension.simple.font.families=fonts.xml

Essa configuração registra a extensão de fontes e indica o arquivo XML que contém a definição da família Toyota Text.

3. Definir a família de fontes

Crie o arquivo fonts.xml com o seguinte conteúdo:

<?xml version="1.0" encoding="UTF-8"?>
<fontFamilies>
    <fontFamily name="nome">
        <normal><![CDATA[fonts/Regular.ttf]]></normal>
        <bold><![CDATA[fonts/Bold.ttf]]></bold>
        <italic><![CDATA[fonts/Italic.ttf]]></italic>
        <boldItalic><![CDATA[fonts/BoldItalic.ttf]]></boldItalic>
        <pdfEncoding><![CDATA[Identity-H]]></pdfEncoding>
        <pdfEmbedded>true</pdfEmbedded>
    </fontFamily>
</fontFamilies>

Nessa configuração:

fontFamily name: define o nome da família de fontes que será referenciada no relatório.
normal, bold, italic e boldItalic: indicam os arquivos correspondentes a cada estilo.
pdfEncoding: define a codificação utilizada na geração do PDF.
pdfEmbedded: indica que a fonte deve ser incorporada ao PDF gerado.

Confirme se os arquivos disponibilizados incluem todos os estilos declarados. Caso algum estilo não esteja disponível, ajuste a configuração conforme os arquivos existentes e as regras de substituição de fontes do JasperReports.

4. Empacotar os arquivos do relatório

Inclua o JAR da extensão de fontes no pacote ZIP do relatório.
Exemplo de estrutura:

Person.zip
├── Person.jrxml
├── text-fonts.jar
├── imagens/
└── outros arquivos necessários

O arquivo JRXML deve seguir a convenção de nomenclatura e empacotamento exigida pela plataforma. Inclua também os sub-relatórios, as imagens e os demais recursos utilizados pelo relatório, quando aplicável.

5. Referenciar a fonte no relatório

Nos elementos de texto do arquivo JRXML, utilize o nome da família definido no fonts.xml.

Exemplo:

<textElement>
    <font fontName="Text" size="12"/>
</textElement>

Adapte o exemplo à estrutura do elemento de texto existente no relatório. Se necessário, configure também os estilos de negrito e itálico.

6. Publicar e validar o relatório

Publique o pacote ZIP conforme o procedimento habitual da plataforma e execute o relatório para validar a renderização da fonte.

Verifique se:

A fonte Text é carregada corretamente.
Os estilos normal, negrito e itálico são exibidos conforme esperado.
Os caracteres especiais e acentuados são renderizados corretamente.
A fonte é incorporada ao PDF, quando essa opção está habilitada.
O resultado permanece correto em diferentes execuções do relatório.

O carregamento da extensão depende de como a plataforma disponibiliza os arquivos do pacote ao mecanismo JasperReports. Caso a fonte não seja reconhecida, valide os logs de execução, a estrutura do JAR e o registro da extensão.

É necessário instalar a fonte no servidor?

Não, o mecanismo de JAR dentro do ZIP é completamente autocontido, não há necessidade de instalar nada no servidor nem solicitar nenhuma alteração de infraestrutura.

Pontos de atenção

Nome da fonte: o nome utilizado no JRXML deve corresponder exatamente ao atributo name declarado no fonts.xml: Text;
Estrutura do JAR: confirme se os arquivos de configuração e as fontes estão nos caminhos declarados;
Incorporação ao PDF: mantenha pdfEmbedded habilitado para solicitar a incorporação da fonte ao documento gerado;
Compatibilidade: valide a configuração com a versão do JasperReports utilizada pela plataforma;
Licenciamento: confirme se a licença da Text permite o uso e a incorporação da fonte nos relatórios distribuídos;
Validação em ambiente de testes: antes de utilizar a configuração em produção, teste a publicação e a geração do relatório no ambiente de homologação.

Olá, como podemos te ajudar?