Artigo Técnico

Fallback automático de fonte para CJK e emojis em PDF

Um template de fatura configurado com Arial imprime "Invoice for" e mais nada. A chamada de texto retornou 1, o arquivo validou, e a extração de texto veio dez caracteres mais curta: cada caractere han de 北京示例科技有限公司 desapareceu, porque a Arial não tem nenhum deles. O fallback automático de fonte na PDF Library for Delphi vem ligado por padrão e puxa esses caracteres de faces instaladas, o AddFontFallback define sua própria ordem de busca, e uma política de missing glyph com relatório JSON trata o que nenhuma face conseguir desenhar

A parte silenciosa é o que torna isso caro. Um PDF com um branco onde deveria estar o nome de uma parte envolvida passa por toda verificação estrutural, abre em qualquer visualizador e geralmente é percebido pelo cliente, não pela sua suíte de testes

Por que texto não suportado desaparece em vez de gerar um erro?

O PDF não tem a noção de uma fonte recusando um caractere, então um glifo ausente não é erro no nível do arquivo. Uma fonte simples mapeia códigos de um byte para nomes de glifo através de uma encoding; uma fonte composta mapeia códigos através de uma CMap para CIDs e depois para índices de glifo. Peça a uma face algo que ela não contém e você cai no índice de glifo zero, o .notdef, que a ISO 32000-1 §9.7.6.3 trata como o resultado padrão para caracteres indefinidos. A maioria das faces desenha o .notdef como nada. Algumas desenham uma caixa vazia

De qualquer forma o content stream está bem formado e a página renderiza. Nada na especificação pede que um produtor verifique cobertura antes de escrever um operador de texto, então um gerador que pula a checagem produz um arquivo em conformidade que perdeu conteúdo silenciosamente. É por isso que fallback e relatório andam juntos. Resolver o que dá para resolver é metade do trabalho; contar o resto para você é a outra metade, e na nossa visão a mais importante para qualquer coisa que carrega um nome ou um valor

Ligando a cadeia de fallback na PDF Library for Delphi

O fallback só entra em ação quando a fonte selecionada realmente não tem um caractere da string, então texto só em latim mantém o caminho normal e não paga nada extra. Uma instância nova de TPDFlib já vem com o fallback automático ligado, então o código de desenho não precisa de chamada extra nenhuma:

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // O fallback automático vem ligado por padrão: emojis, kana, hangul,
    // han e símbolos são procurados em uma tabela de candidatos embutida
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);

    Lib.AddTrueTypeFont('Arial', 2);   // 2 = embute como subconjunto
    Lib.SetTextSize(11);
    Lib.DrawText(72, 720, 'Invoice for 北京示例科技有限公司');
    Lib.DrawText(72, 700, 'Delivery status: on time ✅');

    Lib.SaveToFile('invoice.pdf');
  finally
    Lib.Free;
  end;
end;

Com o fallback automático ligado, a biblioteca escolhe candidatos pelo script de cada caractere não resolvido. A tabela é fixa e orientada a Windows: emojis e pictogramas tentam Segoe UI Emoji, depois Segoe UI Symbol, depois Arial Unicode MS; kana tenta Yu Gothic primeiro; hangul tenta Malgun Gothic primeiro; o bloco han unificado tenta Microsoft YaHei, depois Microsoft JhengHei, Yu Gothic, Malgun Gothic e SimSun; símbolos matemáticos e técnicos vão para Segoe UI Symbol e Cambria Math. Todo o resto cai para uma lista ampla que começa com Nirmala UI e Segoe UI

Faces que você registra com AddFontFallback são tentadas antes dessa tabela embutida, na ordem em que você as adicionou. SetAutomaticFontFallback(0) desliga só a tabela embutida: a cadeia explícita continua ativa, que é a configuração a escolher quando você quer que a saída use suas faces aprovadas e nada mais. O AddFontFallback ignora um nome que já está na lista e retorna a posição dele com base 1, e ClearFontFallbacks, RemoveFontFallback e GetFontFallbackCount permitem reconstruir a cadeia entre documentos

A armadilha da unificação han: quem ganha os caracteres compartilhados?

Chinês, japonês e coreano compartilham a maioria dos ideogramas han do Unicode, mas cada locale espera letterforms diferentes para muitos deles. O code point de 直 ou 骨 é o mesmo em um endereço de Tóquio e um de Pequim; a forma que um leitor nativo espera não é. Uma cadeia de fallback só responde "qual face instalada tem um glifo para esse code point", e toda face CJK tem, então a face que vier primeiro ganha todos os caracteres compartilhados

A tabela automática coloca Microsoft YaHei primeiro para han. Isso é ótimo para chinês simplificado e errado para japonês. Um endereço japonês nessa fatura sai com o kana desenhado pelo Yu Gothic (kana manda a busca para a face japonesa primeiro) e o kanji desenhado pelo YaHei com formas chinesas, tudo na mesma linha. Nada está faltando, o relatório fica vazio, e um leitor japonês percebe na hora que algo está estranho

Nossa recomendação é parar de depender da ordem automática para han e construir a cadeia explícita a partir do locale do documento. Você geralmente já o conhece, pelo cadastro do cliente ou pela língua do template:

procedure ConfigureFallback(Lib: TPDFlib; const Locale: string);
begin
  Lib.ClearFontFallbacks;
  if Locale = 'ja' then
  begin
    Lib.AddFontFallback('Yu Gothic');
    Lib.AddFontFallback('Meiryo');
  end
  else if (Locale = 'zh-TW') or (Locale = 'zh-HK') then
    Lib.AddFontFallback('Microsoft JhengHei')
  else if Locale = 'ko' then
    Lib.AddFontFallback('Malgun Gothic')
  else
    Lib.AddFontFallback('Microsoft YaHei');
  // Emojis, símbolos e qualquer escrita não coberta acima ainda passam
  // pelos candidatos embutidos; passe 0 aqui para proibir isso
  Lib.SetAutomaticFontFallback(1);
end;

Chame uma vez por documento, antes do primeiro DrawText. A ordem dentro da lista explícita importa do mesmo jeito: a primeira face que cobre um caractere ganha, então uma face pan-Unicode como Arial Unicode MS pertence ao fim, se é que pertence a algum lugar. Coloque-a primeiro e ela vai desenhar quase tudo, e as faces específicas por script que você escolheu com cuidado nunca serão consultadas

O fallback opera em clusters inteiros

A PDF Library for Delphi decide o fallback por cluster de grafema, então um cluster é sempre desenhado por uma única face. Uma sílaba devanágari, um emoji com modificador de tom de pele, uma letra base com acentos combináveis: cada um deles é uma única unidade na tela, e as decisões de shaping dentro dele vêm de tabelas de uma fonte em particular. Meio cluster da Arial e meio de uma face de fallback colocaria na página um glifo tecnicamente presente e visivelmente quebrado, o que é argumentavelmente pior que um branco

A fonte selecionada faz o shaping da string primeiro. Só os clusters que voltaram como glifo zero vão procurar outra face, e clusters vizinhos que resolvem para a mesma face são desenhados juntos como uma run, então um nome chinês de dez caracteres vira uma única run do YaHei em vez de dez trocas de fonte separadas. A ordem da direita para a esquerda também é mantida: uma run de fallback dentro de texto árabe ou hebraico fica onde o algoritmo bidirecional a colocou. A mesma maquinaria de shaping alimenta escrita vertical para japonês e chinês

PDF Library for Delphi: diagrama da cadeia de fallback: uma run de clusters CJK não encontra a face primária Arial e é desenhada pelo Microsoft YaHei como primeiro fallback que cobre, e clusters sem cobertura seguem a política de report ou abort
Essa run de clusters passa da face primária ao primeiro fallback que cobre, e só as faces realmente usadas são embutidas. Clusters que nenhuma face consegue desenhar seguem a política de missing glyph: reportar e continuar, ou abortar com o erro 521

Um glifo ausente deve parar o documento?

Depende de para que o documento serve, e a PDF Library for Delphi deixa você escolher com SetMissingGlyphPolicy. PDF_MISSING_GLYPH_REPORT é o padrão: a operação de texto segue, caracteres que nenhuma face consegue desenhar são descartados da saída, e cada um é registrado. PDF_MISSING_GLYPH_ABORT rejeita a operação de texto inteira antes que algo seja escrito na página, o DrawText retorna 0, e o código de erro é 521 (PDFLIB_ERROR_MISSING_GLYPH)

Para relatórios em lote internos, pegue a política de report e registre as lacunas; um relatório ligeiramente incompleto hoje vale mais que nenhum relatório. Para contratos, faturas, certificados e qualquer outra coisa que carrega o nome de uma pessoa ou empresa, pegue abort. Um caractere descartado em nome de uma parte é um defeito que você quer encontrar no seu próprio pipeline, e como o abort acontece antes da escrita, nenhuma linha pela metade fica na página

var
  Lib: TPDFlib;
  Err: Integer;
  Report: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_ABORT);
    Lib.AddTrueTypeFont('Arial', 2);
    Lib.SetTextSize(11);

    if Lib.DrawText(72, 660, CustomerName) <> 1 then
    begin
      Err := Lib.LastErrorCode;   // ler também o reseta de volta para 0
      if Err = PDFLIB_ERROR_MISSING_GLYPH then
      begin
        Report := Lib.GetMissingGlyphReportJSON;
        // {"valid":false,"policy":1,"eventCount":1,"events":[
        //   {"sequence":1,"documentIndex":0,"page":1,"utf16Index":3,
        //    "codePoint":983041,"unicode":"U+F0001",
        //    "fontName":...,"fontType":...,"operation":"DrawText"}]}
        EscalateToOperator(Report);
      end;
    end;
  finally
    Lib.Free;
  end;
end;

Note a variável local. LastErrorCode se limpa quando lido, então código que checa Lib.LastErrorCode = 0 em um lugar e depois registra Lib.LastErrorCode em outro vai registrar 0. Leia uma vez, guarde o valor

Cada evento do relatório carrega a página, o índice UTF-16 dentro da string, o code point em decimal e na forma U+XXXX, a fonte selecionada, o tipo dela e a chamada de API que esbarrou no problema. Com isso, um ticket de suporte cita o caractere exato em vez de descrever um sintoma. A flag valid só é true quando nenhum evento foi registrado, o que a torna um gate barato em um job em lote

A biblioteca guarda os 256 eventos mais recentes e descarta os mais velhos, então um documento cheio de texto não desenhável não consegue transformar diagnóstico em problema de memória. Eventos se acumulam entre documentos na mesma instância de TPDFlib; chame ClearMissingGlyphReport antes de cada documento se quiser um relatório por arquivo, ou use o campo documentIndex para distingui-los

Abortar em letras, tolerar decoração

Uma política única para o documento inteiro às vezes é grosseira demais. Uma etiqueta de envio pode carregar um emoji decorativo ao lado do nome do destinatário, e você preferiria perder o emoji a rejeitar a etiqueta. O evento OnMissingGlyph dispara para cada caractere que nenhuma face da cadeia conseguiu desenhar, recebe a política como ação padrão e pode sobrescrevê-la por code point:

type
  TGlyphGate = class
    procedure MissingGlyph(Sender: TObject; CodePoint: Cardinal;
      UTF16Index, Page: Integer; const FontName, Operation: WideString;
      var Action: Integer);
  end;

procedure TGlyphGate.MissingGlyph(Sender: TObject; CodePoint: Cardinal;
  UTF16Index, Page: Integer; const FontName, Operation: WideString;
  var Action: Integer);
begin
  // Pictogramas e dingbats são decoração: descarte-os e registre
  if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
     ((CodePoint >= $2600) and (CodePoint <= $27BF)) then
    Action := PDF_MISSING_GLYPH_REPORT
  else
    Action := PDF_MISSING_GLYPH_ABORT;   // letras e dígitos não podem sumir
end;

// Ligando o evento
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;

O evento roda depois que o fallback teve sua chance, então só vê caracteres verdadeiramente sem resolução nesta máquina. Cada um deles ainda entra no relatório JSON, qualquer que seja a ação que o handler escolher

Medir, embutir e implantar

O GetTextWidth passa pelas mesmas decisões de fallback cluster a cluster que o DrawText. Parece óbvio, mas é exatamente onde camadas de fallback caseiras costumam errar: elas remendam a chamada de desenho, deixam a medição na fonte primária, e todo total alinhado à direita e coluna de tabela passa a ser calculado com larguras que não correspondem ao que acaba na página. Aqui uma string medida antes de desenhar ocupa a largura em que foi medida, fallback incluído, e é isso que torna razoável deixar o fallback ligado em todo lugar, e não apenas nos templates que você auditou à mão

Uma consequência sob a política de abort: quando a medição esbarra em um caractere sem resolução, o GetTextWidth retorna 0 e define o erro 521. Código de layout que divide por uma largura ou a usa para dimensionar uma célula deve checar isso antes de usar o número

Faces de fallback só são embutidas quando desenham algo. Uma face da cadeia que nunca resolveu um cluster não acrescenta nada ao arquivo, e uma face que resolveu é embutida como subconjunto dos glifos que desenhou. Um documento com um caractere chinês entre 5.000 latinos carrega um glifo han, não uma fonte CJK de vários megabytes; otimização de tamanho de arquivo e subsetting de fontes cobre como esse subconjunto é construído. É por isso que uma cadeia longa cobrindo cada locale que você atende é barata de configurar, e cada PDF paga só pelo que usou. Arquivos produzidos em outro lugar que referenciam fontes que nunca embutiram são um reparo diferente, descrito em embutir fontes ausentes em um PDF existente

A ressalva de implantação é fácil de perder. O fallback resolve contra as fontes instaladas na máquina que roda seu código, e uma estação de trabalho de desenvolvimento com um Office completo tem muito mais delas que uma imagem de servidor enxuta ou um container. Se o Yu Gothic ou o Microsoft YaHei não estiver lá, a cadeia não tem para onde cair. Rode um documento com um nome han, um nome em hangul e um emoji no servidor de destino e leia o relatório JSON: um array events vazio ali diz mais que qualquer teste no seu desktop. Distribua as fontes de que depende e confira se as licenças delas permitem embutir

A mesma cadeia de fallback, política de missing glyph e relatório são expostos nas edições DLL e ActiveX, então chamadores C#, C++ ou scripting os configuram com as mesmas chamadas. A documentação de referência e os downloads estão na página do produto PDF Library for Delphi