Technisch artikel

Automatische fontfallback voor CJK en emoji in Delphi

Een factuursjabloon gezet in Arial print "Invoice for" en daarna niets. De tekst-aanroep gaf 1 terug, het bestand valideerde, en tekstextractie kwam tien tekens tekort: elk Han-teken in 北京示例科技有限公司 was weg, want Arial heeft er geen. Automatische fontfallback in PDF Library for Delphi staat standaard aan en haalt zulke tekens uit geïnstalleerde lettertypen, AddFontFallback stelt je eigen zoekvolgorde in, en een missing-glyph-beleid met een JSON-rapport vangt op wat geen enkel lettertype kan tekenen

Het stille eraan is wat het duur maakt. Een PDF met een leegte waar een bedrijfsnaam hoort te staan haalt elke structurele check, opent in elke viewer en wordt meestal door de klant opgemerkt in plaats van door je testsuite

Waarom verdwijnt niet-ondersteunde tekst in plaats van een fout te geven?

PDF kent geen notie van een lettertype dat een teken weigert, dus een ontbrekende glyph is op bestandsniveau geen fout. Een simple font mapt één-byte-codes via een encoding op glyph-namen; een composite font mapt codes via een CMap op CIDs en daarna op glyph-indexen. Vraag een lettertype om iets dat het niet bevat en je belandt op glyph-index nul, .notdef, dat ISO 32000-1 §9.7.6.3 als de standaarduitkomst voor ongedefinieerde tekens behandelt. De meeste lettertypen tekenen .notdef als helemaal niets. Sommige tekenen een leeg kadertje

Hoe dan ook is de content-stream goed gevormd en rendert de pagina. Niets in de specificatie vraagt een producent om de dekking te controleren vóór het schrijven van een tekstoperator, dus een generator die de check overslaat produceert een conformerend bestand dat stilletjes content is kwijtgeraakt. Daarom horen fallback en rapportage bij elkaar. Oplossen wat oplosbaar is, is de halve klus; je vertellen wat overblijft is de andere helft, en wat ons betreft de belangrijkste voor alles waarop een naam of een bedrag staat

De fallback-keten aanzetten in PDF Library for Delphi

Fallback springt er alleen bij wanneer het gekozen lettertype echt een teken uit de string mist, dus Latijnse tekst houdt zijn normale pad en kost niets extra's. Een nieuwe TPDFlib-instantie heeft automatische fallback al aangaan, dus de tekencode heeft helemaal geen extra aanroep nodig:

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // Automatische fallback staat standaard aan: emoji, kana, Hangul,
    // Han en symbolen worden opgezocht in een ingebouwde kandidatentabel
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);

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

Met automatische fallback aan kiest de library kandidaten op het schrift van elk onopgelost teken. De tabel is vast en Windows-gericht: emoji en pictografen proberen Segoe UI Emoji, dan Segoe UI Symbol, dan Arial Unicode MS; kana probeert eerst Yu Gothic; Hangul probeert eerst Malgun Gothic; het verenigde Han-blok probeert Microsoft YaHei, dan Microsoft JhengHei, Yu Gothic, Malgun Gothic en SimSun; wiskundige en technische symbolen gaan naar Segoe UI Symbol en Cambria Math. Al de rest valt door naar een brede lijst die begint met Nirmala UI en Segoe UI

Lettertypen die je met AddFontFallback registreert worden vóór die ingebouwde tabel geprobeerd, in de volgorde waarin je ze toevoegde. SetAutomaticFontFallback(0) zet alleen de ingebouwde tabel uit: de expliciete keten blijft actief, de instelling om te kiezen wanneer je wilt dat de uitvoer jouw goedgekeurde lettertypen gebruikt en niets anders. AddFontFallback negeert een naam die al in de lijst staat en geeft zijn positie vanaf 1 terug, en ClearFontFallbacks, RemoveFontFallback en GetFontFallbackCount laten je de keten tussen documenten door herbouwen

De Han-unificatieval: wie wint de gedeelde tekens?

Chinees, Japans en Koreaans delen de meeste Han-ideogrammen in Unicode, maar elke locale verwacht voor veel daarvan andere lettervormen. Het codepunt van 直 of 骨 is hetzelfde in een Tokioos en een Pekings adres; de vorm die een moedertaallezer verwacht is dat niet. Een fallback-keten antwoordt alleen op de vraag welk geïnstalleerd lettertype een glyph voor dit codepunt heeft, en dat heeft elk CJK-lettertype, dus welk lettertype eerst komt wint elk gedeeld teken

De automatische tabel zet Microsoft YaHei eerst voor Han. Dat is prima voor vereenvoudigd Chinees en verkeerd voor Japans. Een Japans adres op die factuur komt naar buiten met kana getekend door Yu Gothic (kana stuurt de opzoeking eerst naar het Japanse lettertype) en kanji getekend door YaHei met Chinese vormen, allemaal op één regel. Niets ontbreekt, het rapport blijft leeg, en een Japanse lezer ziet meteen dat er iets niet klopt

Onze aanbeveling is om voor Han niet op de automatische volgorde te leunen en de expliciete keten op te bouwen vanuit de locale van het document. Die ken je meestal al, uit het klantenrecord of de sjabloontaal:

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, symbolen en elk schrift dat hierboven niet gedekt is gaan nog
  // steeds door de ingebouwde kandidaten; geef hier 0 door om dat te verbieden
  Lib.SetAutomaticFontFallback(1);
end;

Roep het één keer per document aan, vóór de eerste DrawText. De volgorde binnen de expliciete lijst weegt net zo: het eerste lettertype dat een teken dekt wint, dus een pan-Unicode-lettertype als Arial Unicode MS hoort aan het einde, als het al ergens hoort. Zet je het vooraan, dan tekent het bijna alles en worden de script-specifieke lettertypen die je met zorg koos nooit meer geraadpleegd

Fallback werkt op hele clusters

PDF Library for Delphi beslist fallback per grafeemcluster, dus één cluster wordt altijd door één lettertype getekend. Een Devanagari-lettergreep, een emoji met een skin-tone-modifier, een basisletter met combinerende accenten: elk daarvan is op het scherm één eenheid, en de shaping-beslissingen erbinnen komen uit tabellen van één specifiek lettertype. De halve cluster uit Arial en de andere helft uit een fallback-lettertype zou een glyph op de pagina zetten die technisch aanwezig en zichtbaar kapot is, wat nog erger is dan een leegte

Het gekozen lettertype geeft de string eerst vorm. Alleen clusters die als glyph nul terugkwamen gaan op zoek naar een ander lettertype, en naburige clusters die op hetzelfde lettertype uitkomen worden samen als één run getekend, dus een Chinese naam van tien tekens wordt één YaHei-run in plaats van tien losse lettertypewissels. Rechts-naar-links-volgorde blijft ook staan: een fallback-run in Arabische of Hebreeuwse tekst staat waar het bidirectionele algoritme hem neerzette. Dezelfde shaping-mechaniek drijft verticaal schrijven voor Japans en Chinees

PDF Library for Delphi: Diagram van de fallback-keten: een CJK-clusterrun mist het primaire Arial-lettertype, wordt getekend door Microsoft YaHei als eerste dekkende fallback, en niet-gedekte clusters volgen het rapportage- of afbreekbeleid
Deze clusterrun valt terug van het primaire lettertype naar de eerste dekkende fallback, en alleen daadwerkelijk gebruikte lettertypen worden ingesloten. Clusters die geen enkel lettertype kan tekenen volgen het missing-glyph-beleid: rapporteren en doorgaan, of afbreken met fout 521

Moet een ontbrekende glyph het document stoppen?

Dat hangt af van waar het document voor dient, en PDF Library for Delphi laat je kiezen met SetMissingGlyphPolicy. PDF_MISSING_GLYPH_REPORT is de default: de tekstbewerking gaat door, tekens die geen lettertype kan tekenen vallen uit de uitvoer, en elk ervan wordt geregistreerd. PDF_MISSING_GLYPH_ABORT wijst de hele tekstbewerking af voordat er iets op de pagina wordt geschreven, DrawText geeft 0 terug, en de foutcode is 521 (PDFLIB_ERROR_MISSING_GLYPH)

Voor interne batchrapporten: neem het rapportbeleid en log de gaten; een licht incompleet rapport vandaag is beter dan geen rapport. Voor contracten, facturen, certificaten en alles anders dat de naam van een persoon of bedrijf draagt: neem abort. Een weggevallen teken in een partijnaam is een defect dat je in je eigen pipeline wilt vinden, en omdat de afbraak vóór het schrijven gebeurt blijft er geen halfgetekende regel op de pagina achter

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;   // lezen zet hem ook terug op 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;

Merk op de lokale variabele. LastErrorCode wist zichzelf bij het lezen, dus code die op de ene plek Lib.LastErrorCode = 0 controleert en op de andere Lib.LastErrorCode logt, logt 0. Lees hem één keer, bewaar de waarde

Elk rapport-event draagt de pagina, de UTF-16-index binnen de string, het codepunt in decimaal en in U+XXXX-vorm, het gekozen lettertype, zijn type en de API-aanroep die het probleem raakte. Daarmee noemt een supportticket het exacte teken in plaats van een symptoom te omschrijven. De valid-vlag is alleen true wanneer er geen events zijn geregistreerd, wat het een goedkope poortwachter maakt in een batchjob

De library bewaart de 256 meest recente events en gooit oudere weg, dus een document vol onrenderbare tekst kan van diagnostics geen geheugenprobleem maken. Events stapelen op over documenten op dezelfde TPDFlib-instantie; roep ClearMissingGlyphReport vóór elk document aan als je één rapport per bestand wilt, of gebruik het veld documentIndex om ze uit elkaar te houden

Afbreken op letters, decoratie tolereren

Eén beleid voor het hele document is soms te bot. Een verzendlabel kan naast de naam van de ontvanger een decoratieve emoji dragen, en je verliest liever de emoji dan het label af te wijzen. Het OnMissingGlyph-event aait voor elk teken dat geen lettertype in de keten kon tekenen, krijgt het beleid als standaardactie mee, en kan het per codepunt overrulen:

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
  // Pictografen en dingbats zijn decoratie: laten vallen en registreren
  if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
     ((CodePoint >= $2600) and (CodePoint <= $27BF)) then
    Action := PDF_MISSING_GLYPH_REPORT
  else
    Action := PDF_MISSING_GLYPH_ABORT;   // letters en cijfers mogen niet verdwijnen
end;

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

Het event draait nadat fallback zijn kans heeft gehad, dus het ziet alleen tekens die op deze machine echt onoplosbaar zijn. Elk ervan belandt alsnog in het JSON-rapport, welke actie de handler ook kiest

Meten, insluiten en uitrollen

GetTextWidth loopt door dezelfde cluster-voor-cluster-fallbackbeslissingen als DrawText. Dat klinkt vanzelfsprekend, maar het is precies waar zelfgebouwde fallback-lagen het vaakst misgaan: ze patchen de tekenaanroep, laten meting op het primaire lettertype staan, en elke rechts uitgelijnde totaal- en tabelkolom wordt dan berekend uit breedtes die niet matchen met wat er uiteindelijk op de pagina staat. Hier neemt een string die vóór het tekenen wordt gemeten de breedte in waarop hij gemeten is, fallback-runs inbegrepen, en dat is wat het redelijk maakt om fallback overal aan te laten in plaats van alleen in de sjablonen die je met de hand hebt gecontroleerd

Eén gevolg onder het abort-beleid: wanneer meting op een onoplosbaar teken stuit, geeft GetTextWidth 0 terug en zet fout 521. Layoutcode die door een breedte deelt of een cel ermee laat measuren moet daar eerst op controleren

Fallback-lettertypen worden alleen ingesloten wanneer ze iets tekenen. Een lettertype in de keten dat nooit een cluster oploste voegt niets toe aan het bestand, en een lettertype dat dat wel deed wordt ingesloten als subset van de glyphs die het tekende. Een document met één Chinees teken tussen 5.000 Latijnse draagt één Han-glyph mee, geen CJK-lettertype van enkele megabytes; bestandsgrootte-optimalisatie en font-subsetting beschrijft hoe die subset wordt gebouwd. Daarom is een lange keten die elke locale dekt die je bedient goedkoop in te stellen, en elke PDF betaalt alleen voor wat hij gebruikte. Bestanden die elders zijn gemaakt en naar lettertypen verwijzen die ze nooit insloten zijn een andere reparatie, beschreven in ontbrekende fonts insluiten in een bestaande PDF

De uitrol-caveat is makkelijk te missen. Fallback lost op tegen de fonts die op de machine zijn geïnstalleerd waar je code draait, en een ontwikkelwerkstation met een volledige Office-installatie heeft er veel meer dan een kaal serverimage of container. Zit Yu Gothic of Microsoft YaHei er niet in, dan heeft de keten niets om op terug te vallen. Draai één document met een Han-naam, een Hangul-naam en een emoji op de doelserver en lees het JSON-rapport: een lege events-array daar vertelt je meer dan welke test op je eigen desktop ook. Schep de fonts in waar je van afhankelijk bent, en controleer dat hun licenties insluiten toestaan

Dezelfde fallback-keten, hetzelfde missing-glyph-beleid en hetzelfde rapport worden ook via de DLL- en ActiveX-edities aangeboden, dus C#, C++ of scripting-aanroepers stellen ze in met dezelfde aanroepen. Referentiedocumentatie en downloads staan op de PDF Library for Delphi productpagina