Articolo tecnico

PDF Library for Delphi: fallback font per CJK ed emoji

Un set di template per fatture composto in Arial stampa "Invoice for" e poi più niente. La chiamata di testo ha restituito 1, il file passa la validazione, e l'estrazione del testo risulta corta di dieci caratteri: ogni carattere Han di 北京示例科技有限公司 è sparito, perché Arial non ne ha nessuno. Il fallback automatico dei font in PDF Library for Delphi è attivo per default e recupera questi caratteri dalle face installate, AddFontFallback imposta il tuo ordine di ricerca, e una policy per i glifi mancanti con report JSON si occupa di ciò che nessuna face sa disegnare

La parte silenziosa è ciò che rende il problema costoso. Un PDF con un vuoto dove dovrebbe stare il nome di una controparte passa ogni controllo strutturale, si apre in ogni viewer, e di solito se ne accorge il cliente piuttosto che la tua suite di test

Perché il testo non supportato svanisce invece di generare un errore?

PDF non ha alcun concetto di font che rifiuta un carattere, quindi un glifo mancante non è un errore a livello di file. Un font semplice mappa codici a un byte su nomi di glifo tramite una codifica; un font composito mappa i codici tramite una CMap su CID e poi su indici di glifo. Chiedi a una face qualcosa che non contiene e atterri sull'indice di glifo zero, .notdef, che ISO 32000-1 §9.7.6.3 tratta come esito standard per i caratteri non definiti. La maggior parte delle face disegna .notdef come niente affatto. Alcune disegnano un riquadro vuoto

In entrambi i casi il content stream è ben formato e la pagina si renderizza. Niente nella specifica chiede a un producer di controllare la copertura prima di scrivere un operatore di testo, quindi un generatore che salta il controllo produce un file conforme che ha perso contenuto in silenzio. Ecco perché fallback e report vanno insieme. Risolvere ciò che può essere risolto è metà del lavoro; dirti il resto è l'altra metà, e a nostro avviso quella più importante per qualsiasi cosa porti sopra un nome o un importo

Attivare la catena di fallback in PDF Library for Delphi

Il fallback scatta solo quando il font selezionato manca davvero di un carattere nella stringa, quindi il testo solo latino tiene il suo percorso normale e non paga nulla in più. Una nuova istanza di TPDFlib ha già il fallback automatico attivo, così il codice di disegno non ha bisogno di alcuna chiamata extra:

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // Il fallback automatico è attivo per default: emoji, kana, Hangul,
    // Han e simboli vengono cercati in una tabella di candidati integrata
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);

    Lib.AddTrueTypeFont('Arial', 2);   // 2 = incorpora come subset
    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;

Con il fallback automatico attivo, la libreria sceglie i candidati in base allo script di ogni carattere non risolto. La tabella è fissa e orientata a Windows: emoji e pittogrammi provano Segoe UI Emoji, poi Segoe UI Symbol, poi Arial Unicode MS; i kana provano prima Yu Gothic; l'Hangul prova prima Malgun Gothic; il blocco Han unificato prova Microsoft YaHei, poi Microsoft JhengHei, Yu Gothic, Malgun Gothic e SimSun; i simboli matematici e tecnici vanno a Segoe UI Symbol e Cambria Math. Tutto il resto cade in una lista ampia che inizia con Nirmala UI e Segoe UI

Le face che registri con AddFontFallback vengono provate prima di quella tabella integrata, nell'ordine in cui le hai aggiunte. SetAutomaticFontFallback(0) spegne solo la tabella integrata: la catena esplicita resta attiva, ed è l'impostazione da scegliere quando vuoi che l'output usi le tue face approvate e nient'altro. AddFontFallback ignora un nome già presente nella lista e restituisce la sua posizione in base 1, e ClearFontFallbacks, RemoveFontFallback e GetFontFallbackCount ti lasciano ricostruire la catena tra un documento e l'altro

La trappola dell'unificazione Han: chi vince i caratteri condivisi?

Cinese, giapponese e coreano condividono la maggior parte degli ideogrammi Han di Unicode, ma ogni locale si aspetta letterform diverse per molti di loro. Il code point di 直 o 骨 è lo stesso in un indirizzo di Tokyo e uno di Pechino; la forma che un lettore nativo si aspetta non lo è. Una catena di fallback risponde solo a "quale face installata ha un glifo per questo code point", e ogni face CJK ce l'ha, quindi la face che arriva prima vince ogni carattere condiviso

La tabella automatica mette Microsoft YaHei prima per l'Han. Va bene per il cinese semplificato ed è sbagliato per il giapponese. Un indirizzo giapponese su quella fattura esce con i kana disegnati da Yu Gothic (i kana mandano la ricerca prima alla face giapponese) e i kanji disegnati da YaHei con forme cinesi, tutto in una riga sola. Non manca niente, il report resta vuoto, e un lettore giapponese vede all'istante che qualcosa non va

La nostra raccomandazione è smettere di fare affidamento sull'ordine automatico per l'Han e costruire la catena esplicita a partire dal locale del documento. Di solito lo conosci già, dal record del cliente o dalla lingua del 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');
  // Emoji, simboli e qualsiasi script non coperto qui sopra passano comunque
  // per i candidati integrati; passa 0 qui per vietarlo
  Lib.SetAutomaticFontFallback(1);
end;

Chiamalo una volta per documento, prima del primo DrawText. L'ordine dentro la lista esplicita conta allo stesso modo: la prima face che copre un carattere vince, quindi una face pan-Unicode come Arial Unicode MS sta alla fine, se proprio ci sta. Mettila per prima e disegnerà quasi tutto, e le face specifiche per script scelte con cura non verranno mai consultate

Il fallback lavora su cluster interi

PDF Library for Delphi decide il fallback per cluster di grafemi, così un cluster viene sempre disegnato da una sola face. Una sillaba devanagari, un'emoji con un modificatore di tono della pelle, una lettera base con segni diacritici combinanti: ognuno è una singola unità sullo schermo, e le decisioni di shaping al suo interno vengono da tabelle di un font preciso. Mezzo cluster da Arial e mezzo da una face di fallback metterebbe sulla pagina un glifo tecnicamente presente e visibilmente rotto, il che è probabilmente peggio di un vuoto

Il font selezionato fa lo shaping della stringa per primo. Solo i cluster tornati come glifo zero vanno a cercare un'altra face, e i cluster vicini che risolvono alla stessa face vengono disegnati insieme come un run solo, così un nome cinese di dieci caratteri diventa un unico run YaHei invece di dieci cambi di font separati. Anche l'ordine da destra a sinistra viene preservato: un run di fallback dentro testo arabo o ebraico sta dove l'algoritmo bidirezionale l'ha messo. La stessa macchina di shaping guida la scrittura verticale per giapponese e cinese

PDF Library for Delphi: diagramma della catena di fallback: una sequenza di cluster CJK non trova la face primaria Arial, viene disegnata da Microsoft YaHei come primo fallback coprente, e i cluster non coperti seguono la policy di report o abort
Questa sequenza di cluster passa dalla face primaria al primo fallback in grado di coprirla, e vengono incorporate solo le face effettivamente utilizzate. I cluster che nessuna face sa disegnare seguono la policy per i glifi mancanti: report e continua, oppure abort con errore 521

Un glifo mancante deve fermare il documento?

Dipende da cosa ci devi fare con il documento, e PDF Library for Delphi ti lascia scegliere con SetMissingGlyphPolicy. PDF_MISSING_GLYPH_REPORT è il valore predefinito: l'operazione di testo va avanti, i caratteri che nessuna face sa disegnare vengono scartati dall'output, e ognuno viene registrato. PDF_MISSING_GLYPH_ABORT rifiuta l'intera operazione di testo prima che qualcosa venga scritto sulla pagina, DrawText restituisce 0, e il codice di errore è 521 (PDFLIB_ERROR_MISSING_GLYPH)

Per i report batch interni, prendi la policy report e logga le lacune; un report leggermente incompleto oggi batte nessun report. Per contratti, fatture, certificati e qualsiasi altra cosa porti il nome di una persona o di una società, prendi abort. Un carattere scartato nel nome di una controparte è un difetto che vuoi trovare nella tua pipeline, e siccome l'abort avviene prima della scrittura, sulla pagina non resta nessuna riga disegnata a metà

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;   // leggerlo lo riporta anche a 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;

Fai attenzione alla variabile locale. LastErrorCode si azzera quando viene letto, quindi codice che controlla Lib.LastErrorCode = 0 in un punto e poi logga Lib.LastErrorCode in un altro loggerà 0. Leggilo una volta sola e conserva il valore

Ogni evento del report porta la pagina, l'indice UTF-16 dentro la stringa, il code point in decimale e in forma U+XXXX, il font che era stato selezionato, il suo tipo e la chiamata API che ha incontrato il problema. Con quelli, un ticket di supporto nomina il carattere esatto invece di descrivere un sintomo. Il flag valid è true solo quando non è stato registrato nessun evento, il che ne fa un gate economico in un job batch

La libreria conserva i 256 eventi più recenti e scarta i più vecchi, così un documento pieno di testo non renderizzabile non può trasformare la diagnostica in un problema di memoria. Gli eventi si accumulano attraverso i documenti sulla stessa istanza di TPDFlib; chiama ClearMissingGlyphReport prima di ogni documento se vuoi un report per file, oppure usa il campo documentIndex per distinguerli

Abortire sulle lettere, tollerare la decorazione

Una policy unica per tutto il documento a volte è troppo grossolana. Un'etichetta di spedizione può portare un'emoji decorativa accanto al nome del destinatario, e preferiresti perdere l'emoji che rifiutare l'etichetta. L'evento OnMissingGlyph scatta per ogni carattere che nessuna face nella catena è riuscita a disegnare, riceve la policy come azione predefinita, e può sovrascriverla per singolo 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
  // I pittogrammi e i dingbat sono decorazione: scartali e registrali
  if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
     ((CodePoint >= $2600) and (CodePoint <= $27BF)) then
    Action := PDF_MISSING_GLYPH_REPORT
  else
    Action := PDF_MISSING_GLYPH_ABORT;   // lettere e cifre non devono sparire
end;

// Collegamento
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;

L'evento gira dopo che il fallback ha avuto la sua possibilità, quindi vede solo i caratteri davvero irrisolvibili su questa macchina. Ognuno di loro finisce comunque nel report JSON, qualunque azione scelga l'handler

Misurare, incorporare e distribuire

GetTextWidth passa attraverso le stesse decisioni di fallback cluster per cluster di DrawText. Sembra ovvio, ma è esattamente il punto in cui i livelli di fallback fatti in casa tendono a sbagliare: toppano la chiamata di disegno, lasciano la misurazione sul font primario, e ogni totale allineato a destra e ogni colonna di tabella viene calcolato da larghezze che non corrispondono a ciò che finisce sulla pagina. Qui una stringa misurata prima del disegno occupa la larghezza con cui è stata misurata, run di fallback inclusi, ed è ciò che rende ragionevole lasciare il fallback attivo ovunque invece che solo nei template che hai verificato a mano

Una conseguenza con la policy abort: quando la misurazione incontra un carattere irrisolvibile, GetTextWidth restituisce 0 e imposta l'errore 521. Il codice di layout che divide per una larghezza o la usa per dimensionare una cella dovrebbe controllarlo prima di usare il numero

Le face di fallback vengono incorporate solo quando disegnano qualcosa. Una face nella catena che non ha mai risolto un cluster non aggiunge nulla al file, e una che l'ha fatto viene incorporata come subset dei glifi che ha disegnato. Un documento con un carattere cinese in mezzo a 5.000 latini porta un glifo Han, non un font CJK di svariati megabyte; ottimizzazione delle dimensioni del file e font subsetting copre come viene costruito quel subset. È per questo che una catena lunga che copre ogni locale che servi costa poco da configurare, e ogni PDF paga solo ciò che ha usato. I file prodotti altrove che riferiscono font che non hanno mai incorporato sono una riparazione diversa, descritta in incorporare font mancanti in un PDF esistente

L'avvertenza sul deployment è facile da perdere. Il fallback si risolve rispetto ai font installati sulla macchina che esegue il tuo codice, e una workstation di sviluppo con un Office completo ne ha molti di più di una immagine server o di un container spogliato. Se Yu Gothic o Microsoft YaHei non ci sono, la catena non ha nulla a cui ricorrere. Fai girare un documento con un nome Han, un nome Hangul e un'emoji sul server di destinazione e leggi il report JSON: un array events vuoto lì dentro ti dice più di qualsiasi test sul tuo desktop. Distribuisci i font da cui dipendi, e controlla che le loro licenze permettano l'incorporazione

La stessa catena di fallback, la stessa policy per i glifi mancanti e lo stesso report sono esposti anche attraverso le edizioni DLL e ActiveX, così i chiamanti C#, C++ o da scripting li configurano con le stesse chiamate. La documentazione di riferimento e i download sono sulla pagina prodotto di PDF Library for Delphi