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
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