Fontes SVG no resvg: carregue a fonte da sua arte

Para renderizar fontes SVG de forma confiável com resvg, forneça os arquivos de fonte ao renderizador e use seus nomes de família no SVG. Na integração nativa Node, @resvg/resvg-js, isso significa configurar fontFiles; defina loadSystemFonts: false quando quiser testar exatamente quais fontes seu processo recebe. O exemplo Node do projeto demonstra essa configuração.

Um PNG pode parecer completo enquanto usa a fonte errada. Confira as formas das letras mesmo quando o comando de exportação termina com sucesso.

Três entradas de fonte, um SVG

Criamos um pequeno emblema de montanha com traçados e colocamos o texto editável PINE & FIELD ao lado dele. O SVG solicita a família Abel em peso regular. Renderizamos a mesma origem três vezes com @resvg/resvg-js 2.6.2, Node 22.19.0 e macOS arm64. A descoberta de fontes do sistema foi desativada em todos os casos.

Teste controlado de carregamento de fontes

Essas observações descrevem este exemplo e esta configuração. Elas não estabelecem qual substituta outra coleção de fontes, integração ou versão escolherá. O diagnóstico útil é mais simples: uma família solicitada ausente pode produzir texto ausente ou texto substituto aparentemente plausível.

Carregue uma fonte local no resvg-js

Este exemplo usa o pacote Node nativo, não o pacote WebAssembly separado. As definições de tipos da versão da integração listam fontFiles, fontDirs e loadSystemFonts na opção font.

Em uma pasta de trabalho nova, instale a versão usada aqui:

npm install --save-exact @resvg/resvg-js@2.6.2

Baixe Abel-Regular.ttf e seu OFL.txt do diretório Abel do Google Fonts. Guarde ambos em uma subpasta fonts. Abel é fornecida sob a SIL Open Font License; mantenha a licença com a fonte ao distribuir este exemplo.

Salve isto como label.svg:

<svg xmlns="http://www.w3.org/2000/svg"
     width="880" height="240" viewBox="0 0 880 240">
  <rect width="880" height="240" fill="#f6f2e8"/>
  <path d="M46 155 L96 57 L147 155 Z" fill="#176b5b"/>
  <path d="M75 155 L112 88 L166 155 Z" fill="#81ab78"/>
  <text x="195" y="151" font-family="Abel"
        font-size="82" font-weight="400" fill="#152e29">
    PINE &amp; FIELD
  </text>
</svg>

Depois salve render.mjs ao lado do SVG:

import { access, readFile, writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { Resvg } from '@resvg/resvg-js';
 
const fontFile = fileURLToPath(
  new URL('./fonts/Abel-Regular.ttf', import.meta.url)
);
await access(fontFile);
 
const svg = await readFile(new URL('./label.svg', import.meta.url));
const renderer = new Resvg(svg, {
  font: {
    loadSystemFonts: false,
    fontFiles: [fontFile],
  },
});
 
const png = renderer.render().asPng();
await writeFile(new URL('./label.png', import.meta.url), png);

Execute node render.mjs. As URLs de arquivo tornam os caminhos de entrada e saída relativos ao script, portanto mudar o diretório de trabalho do terminal não muda qual fonte ele abre. access() fornece um erro direto do sistema de arquivos se a fonte estiver ausente ou inacessível; ele não valida o conteúdo da fonte.

Para reproduzir os controles, deixe o SVG igual. Use um array fontFiles vazio na primeira linha. Na segunda, baixe Anton-Regular.ttf do diretório Anton do Google Fonts, guarde sua licença e forneça esse arquivo no lugar de Abel. Inspecione cada PNG antes de mudar qualquer outra coisa.

Use o nome da família, não o nome do arquivo

Abel-Regular.ttf é um caminho de arquivo. Abel é a família solicitada pelo SVG. Escrever font-family="Abel-Regular.ttf" não manda o renderizador abrir esse arquivo.

O atributo SVG font-family aceita nomes de família ou famílias genéricas, com uma lista de prioridades quando você fornece vários. Ele também tem uma versão CSS: uma declaração CSS font-family correspondente tem precedência sobre o atributo de apresentação.

Para sua própria arte, confira três coisas juntas:

• Família: o nome registrado dentro da fonte e solicitado pelo SVG.
• Estilo e peso: se a face fornecida corresponde às letras pretendidas.
• Caracteres: se a fonte contém as letras e os símbolos do rótulo real.

Um readFile bem-sucedido só comprova que bytes foram lidos. Uma palavra visível só comprova que algumas letras foram renderizadas. Nenhum dos dois prova que a face selecionada é a do seu design.

Para um diagnóstico mais amplo de texto editável versus contornos, veja por que fontes SVG mudam após a exportação.

Confira as mesmas entradas no ambiente de exportação

Trate a fonte como uma entrada do processo da arte. Inclua o arquivo necessário na implantação ou no pacote da tarefa e confirme que o caminho resolvido aponta para ele nesse ambiente. Uma fonte instalada no notebook de design é fácil de esquecer ao montar um processo de servidor.

Comece com a descoberta do sistema desativada e a menor lista explícita de fontes que cubra seu rótulo de teste. Quando essa saída estiver correta, teste as palavras, pontuações, pesos e idiomas reais usados na arte. Nosso rótulo latino regular não testa outros sistemas de escrita nem famílias complexas de fontes.

Se as letras ainda parecerem erradas, inspecione a origem em busca de substituições CSS e estilos de <tspan> aninhados. Se o emblema e o rótulo estiverem ambos recortados ou escalados de forma inesperada, investigue os limites SVG e as dimensões raster separadamente. Nosso passo a passo de tamanho no CairoSVG aborda essa distinção em outro renderizador; suas opções são específicas do CairoSVG.

Ao compartilhar um relato de erro ou um processo de exportação reproduzível, inclua o SVG, a versão exata da integração, os nomes e versões dos arquivos de fonte, as opções do renderizador e uma imagem esperada. Considere as permissões de redistribuição de fontes ao empacotar os arquivos.

Guarde a origem editável ao lado do PNG

O código acima grava um PNG. Esse é um arquivo raster de entrega; suas letras visíveis não são mais texto SVG editável. Guarde label.svg e as fontes de entrada como origem para mudanças futuras no texto.

Se o destinatário precisar de um logo vetorial com letras fixas, prepare uma cópia separada de entrega SVG com contornos no editor vetorial e inspecione-a ali. Mantenha o original com texto editável. Nosso guia de formatos de arquivo de logo explica quais arquivos de origem e entrega atendem a tarefas diferentes.

Se o emblema necessário existe apenas em PNG ou JPG, o vetorizador de logos do PerfectVector pode ajudar a recuperar arte vetorial para essa parte do design. Inspecione os traçados resultantes, remova quaisquer letras traçadas indesejadas e redigite o rótulo com uma fonte conhecida antes de executar a exportação resvg. A vetorização não identifica a fonte original nem restaura texto editável. O guia de vetorização de imagens explica o que essa conversão muda.

Perguntas frequentes

Por que o texto desaparece quando desativo as fontes do sistema? Em nosso teste sem fontes, o renderizador não tinha nenhuma face fornecida para o rótulo editável, portanto apenas a arte de traçados apareceu. Carregue explicitamente uma fonte adequada e confira sua família, estilo e cobertura de caracteres.

Posso usar o nome do arquivo de fonte como nome da família SVG? Use o nome de família da fonte no SVG. Passe o nome do arquivo local separadamente por fontFiles. Renomear um arquivo de fonte não muda seu nome interno de família.

O resvg transforma meu logo PNG em SVG editável? O exemplo aqui renderiza SVG em PNG. Ele não vetoriza um logo raster. Recupere o emblema com um fluxo de vetorização, se necessário, adicione texto editável e guarde esse SVG como original.

Fontes

1. resvg-js — README da versão 2.6.2 — Uso nativo Node e carregamento explícito de fontes.
2. resvg-js — Definições de tipos da versão 2.6.2 — Configuração de fontes e API de imagem renderizada.
3. MDN — SVG font-family — Listas de família e precedência CSS.
4. Google Fonts — Abel — A face regular e a licença usadas no rótulo pretendido.
5. Google Fonts — Anton — A fonte e a licença usadas no controle de substituição.

Se um emblema raster estiver atrasando a arte, vetorize a arte do logo, confira suas bordas no editor e adicione o rótulo como texto editável. Depois renderize com um arquivo explícito de fonte e compare o PNG com seu original antes de entregar.