Eine in Arial gesetzte Rechnungsvorlage druckt "Invoice for" und dann nichts. Der Textaufruf gab 1 zurück, die Datei war valid, und die Textextraktion kam zehn Zeichen zu kurz zurück: Jedes Han-Zeichen in 北京示例科技有限公司 war weg, denn Arial hat keines davon. Der automatische Font-Fallback in PDF Library for Delphi ist standardmäßig aktiviert und zieht solche Zeichen aus installierten Schriftschnitten, AddFontFallback setzt die eigene Suchreihenfolge, und eine Missing-Glyph-Richtlinie mit JSON-Report kümmert sich um das, was kein Schriftschnitt darstellen kann
Das Lautlose ist es, was das teuer macht. Ein PDF mit einer Lücke, wo ein Parteiname stehen sollte, besteht jede strukturelle Prüfung, öffnet sich in jedem Viewer und fällt normalerweise dem Kunden auf, nicht der eigenen Testsuite
Warum verschwindet nicht unterstützter Text, statt einen Fehler auszulösen?
PDF kennt kein Konzept einer Schriftart, die ein Zeichen verweigert, also ist eine fehlende Glyphe auf Dateiebene kein Fehler. Eine einfache Schriftart bildet Ein-Byte-Codes über eine Kodierung auf Glyphennamen ab; eine zusammengesetzte Schriftart bildet Codes über eine CMap auf CIDs und von dort auf Glyphenindizes ab. Fordert man von einem Schriftschnitt etwas, das er nicht enthält, landet man bei Glyphenindex null, .notdef, was ISO 32000-1 §9.7.6.3 als das Standardergebnis für undefinierte Zeichen behandelt. Die meisten Schriftschnitte zeichnen .notdef als gar nichts, manche als leeres Kästchen
In beiden Fällen ist der Content-Stream wohlgeformt und die Seite rendert. Nichts in der Spezifikation verlangt, dass ein Erzeuger die Abdeckung prüft, bevor er einen Textoperator schreibt, also produziert ein Generator, der die Prüfung überspringt, eine konforme Datei, die stillschweigend Inhalt verloren hat. Deshalb gehören Fallback und Meldung zusammen. Zu lösen, was sich lösen lässt, ist die halbe Aufgabe; über den Rest zu berichten die andere Hälfte, und nach unserer Ansicht die wichtigere für alles, auf dem ein Name oder ein Betrag steht
Die Fallback-Kette in PDF Library for Delphi einschalten
Fallback greift nur, wenn die gewählte Schriftart ein Zeichen der Zeichenkette tatsächlich nicht hat, also bleibt rein lateinischer Text auf seinem normalen Pfad und kostet nichts extra. Eine neue TPDFlib-Instanz hat den automatischen Fallback bereits eingeschaltet, deshalb braucht der Zeichencode überhaupt keinen zusätzlichen Aufruf:
var
Lib: TPDFlib;
begin
Lib := TPDFlib.Create;
try
// Automatischer Fallback ist per Voreinstellung an: Emoji, Kana, Hangul,
// Han und Symbole werden in einer eingebauten Kandidatentabelle nachgeschlagen
Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);
Lib.AddTrueTypeFont('Arial', 2); // 2 = als Subset einbetten
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;
Mit aktivem automatischem Fallback wählt die Bibliothek die Kandidaten nach dem Skript jedes nicht aufgelösten Zeichens. Die Tabelle ist fest und Windows-orientiert: Emoji und Piktografen probieren Segoe UI Emoji, dann Segoe UI Symbol, dann Arial Unicode MS; Kana probiert zuerst Yu Gothic; Hangul zuerst Malgun Gothic; der vereinheitlichte Han-Block probiert Microsoft YaHei, dann Microsoft JhengHei, Yu Gothic, Malgun Gothic und SimSun; Mathe- und technische Symbole gehen an Segoe UI Symbol und Cambria Math. Alles andere fällt durch zu einer breiten Liste, die mit Nirmala UI und Segoe UI beginnt
Schriftschnitte, die Sie mit AddFontFallback registrieren, werden vor dieser eingebauten Tabelle probiert, in der Reihenfolge, in der Sie sie hinzugefügt haben. SetAutomaticFontFallback(0) schaltet nur die eingebaute Tabelle ab: Die explizite Kette bleibt aktiv, das ist die Einstellung, wenn die Ausgabe ausschließlich Ihre freigegebenen Schriftschnitte verwenden soll. AddFontFallback ignoriert einen Namen, der schon in der Liste steht, und gibt seine 1-basierte Position zurück, und ClearFontFallbacks, RemoveFontFallback und GetFontFallbackCount erlauben es, die Kette zwischen Dokumenten neu aufzubauen
Die Han-Vereinheitlichungsfalle: Wer gewinnt die geteilten Zeichen?
Chinesisch, Japanisch und Koreanisch teilen sich den Großteil der Han-Ideografen in Unicode, aber jedes Locale erwartet für viele davon andere Letterforms. Der Code-Punkt von 直 oder 骨 ist in einer Tokioter Adresse derselbe wie in einer Pekinger; die Form, die ein muttersprachlicher Leser erwartet, ist es nicht. Eine Fallback-Kette beantwortet nur die Frage, welcher installierte Schriftschnitt eine Glyphe für diesen Code-Punkt hat, und jeder CJK-Schriftschnitt hat eine, also gewinnt der Schriftschnitt, der zuerst kommt, jedes geteilte Zeichen
Die automatische Tabelle setzt für Han Microsoft YaHei an erster Stelle. Für vereinfachtes Chinesisch ist das richtig, für Japanisch falsch. Eine japanische Adresse auf dieser Rechnung erscheint mit Kana von Yu Gothic (Kana schickt die Suche zuerst zum japanischen Schriftschnitt) und Kanji von YaHei mit chinesischen Formen, alles in einer Zeile. Nichts fehlt, der Bericht bleibt leer, und ein japanischer Leser sieht sofort, dass hier etwas nicht stimmt
Unsere Empfehlung: Verlassen Sie sich bei Han nicht auf die automatische Reihenfolge, sondern bauen Sie die explizite Kette aus dem Locale des Dokuments. In der Regel kennen Sie es ohnehin, aus dem Kundendatensatz oder der Sprache der Vorlage:
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, Symbole und jedes oben nicht abgedeckte Skript laufen
// weiterhin durch die eingebauten Kandidaten; hier 0 übergeben, um das zu verbieten
Lib.SetAutomaticFontFallback(1);
end;
Rufen Sie das einmal pro Dokument auf, vor dem ersten DrawText. Auch innerhalb der expliziten Liste zählt die Reihenfolge genauso: Der erste Schriftschnitt, der ein Zeichen abdeckt, gewinnt, also gehört eine pan-Unicode-Schriftart wie Arial Unicode MS ans Ende, wenn überhaupt. Steht sie vorn, zeichnet sie fast alles, und die sorgfältig gewählten skriptspezifischen Schriftschnitte werden nie konsultiert
Fallback arbeitet auf ganzen Clustern
PDF Library for Delphi entscheidet Fallback pro Graphem-Cluster, sodass ein Cluster immer von einem Schriftschnitt gezeichnet wird. Eine Devanagari-Silbe, ein Emoji mit Hautton-Modifikator, ein Grundbuchstabe mit kombinierenden Akzenten: Jedes davon ist auf dem Bildschirm eine einzige Einheit, und die Shaping-Entscheidungen darin stammen aus Tabellen in einem bestimmten Schriftschnitt. Eine halbe Clusterhälfte von Arial und die andere von einem Fallback-Schnitt würde eine Glyphe auf die Seite bringen, die technisch vorhanden und sichtbar defekt ist – was man durchaus als schlimmer ansehen kann als eine Lücke
Die gewählte Schriftart formt die Zeichenkette zuerst. Nur Cluster, die als Glyphe null zurückkamen, suchen sich einen anderen Schriftschnitt, und benachbarte Cluster, die zum selben Schnitt auflösen, werden als ein Lauf zusammen gezeichnet, sodass ein zehnzeichiger chinesischer Name zu einem einzigen YaHei-Lauf wird statt zu zehn einzelnen Schriftwechseln. Auch die Reihenfolge von Rechts nach Links bleibt erhalten: Ein Fallback-Lauf innerhalb von arabischem oder hebräischem Text sitzt dort, wo der bidirektionale Algorithmus ihn hingelegt hat. Dieselbe Shaping-Maschinerie treibt auch das vertikale Schreiben für Japanisch und Chinesisch an
Soll eine fehlende Glyphe das Dokument stoppen?
Das hängt davon ab, wofür das Dokument gedacht ist, und PDF Library for Delphi lässt Sie mit SetMissingGlyphPolicy wählen. PDF_MISSING_GLYPH_REPORT ist die Voreinstellung: Die Textoperation läuft weiter, Zeichen, die kein Schnitt darstellen kann, fallen aus der Ausgabe heraus, und jedes wird protokolliert. PDF_MISSING_GLYPH_ABORT weist die gesamte Textoperation zurück, bevor irgendwas auf die Seite geschrieben wird, DrawText gibt 0 zurück, und der Fehlercode ist 521 (PDFLIB_ERROR_MISSING_GLYPH)
Für interne Stapelberichte: Report-Richtlinie nehmen und die Lücken mitloggen; ein heute leicht unvollständiger Bericht schlägt gar keinen. Für Verträge, Rechnungen, Zertifikate und alles, was den Namen einer Person oder Firma trägt: Abort. Ein verworfenes Zeichen in einem Parteinamen ist ein Defekt, den Sie lieber in der eigenen Pipeline finden, und weil der Abbruch vor dem Schreiben passiert, bleibt keine halb gezeichnete Zeile auf der Seite zurück
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; // das Lesen setzt ihn auch auf 0 zurück
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;
Beachten Sie die lokale Variable. LastErrorCode löscht sich beim Lesen selbst, also wird Code, der an einer Stelle Lib.LastErrorCode = 0 prüft und an anderer Lib.LastErrorCode loggt, eine 0 loggen. Einmal lesen, den Wert behalten
Jedes Berichtsereignis trägt die Seite, den UTF-16-Index innerhalb der Zeichenkette, den Code-Punkt dezimal und in U+XXXX-Form, die gewählte Schriftart, deren Typ und den API-Aufruf, der auf das Problem stieß. Damit benennt ein Support-Ticket das exakte Zeichen, statt ein Symptom zu beschreiben. Das Flag valid ist nur true, wenn keine Ereignisse protokolliert wurden, was es zu einem billigen Gate in einem Stapellauf macht
Die Bibliothek behält die 256 jüngsten Ereignisse und verwirft ältere, also kann ein Dokument voll nicht renderbaren Texts die Diagnostik nicht zu einem Speicherproblem machen. Ereignisse sammeln sich über Dokumente auf derselben TPDFlib-Instanz; rufen Sie ClearMissingGlyphReport vor jedem Dokument, wenn Sie einen Bericht pro Datei wollen, oder nutzen Sie das Feld documentIndex, um sie auseinanderzuhalten
Brechen bei Buchstaben ab, tolerieren Dekoration
Eine einzelne Richtlinie für das ganze Dokument ist manchmal zu grob. Ein Versandetikett trägt vielleicht ein dekoratives Emoji neben dem Namen des Empfängers, und Sie würden lieber das Emoji verlieren als das Etikett zurückzuweisen. Das Ereignis OnMissingGlyph feuert für jedes Zeichen, das keine Schrift in der Kette darstellen konnte, bekommt die Richtlinie als Standardaktion übergeben und kann sie pro Code-Punkt überschreiben:
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
// Piktografen und Dingbats sind Dekoration: verwerfen und protokollieren
if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
((CodePoint >= $2600) and (CodePoint <= $27BF)) then
Action := PDF_MISSING_GLYPH_REPORT
else
Action := PDF_MISSING_GLYPH_ABORT; // Buchstaben und Ziffern dürfen nicht verschwinden
end;
// Verdrahtung
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;
Das Ereignis läuft, nachdem der Fallback seine Chance hatte, also sieht es nur Zeichen, die auf dieser Maschine wirklich nicht auflösbar sind. Jedes davon landet trotzdem im JSON-Report, ganz gleich, welche Aktion der Handler wählt
Messen, einbetten, ausrollen
GetTextWidth geht durch dieselben Cluster-für-Cluster-Fallback-Entscheidungen wie DrawText. Das klingt selbstverständlich, ist aber genau die Stelle, an der selbstgebaute Fallback-Schichten schiefgehen: Sie flicken den Zeichenaufruf, lassen die Messung auf der primären Schriftart, und schon wird jede rechtsbündige Summe und jede Tabellenspalte aus Breiten berechnet, die nicht zu dem passen, was auf der Seite landet. Hier belegt eine vor dem Zeichnen gemessene Zeichenkette exakt die Breite, mit der sie gemessen wurde, Fallback-Läufe eingeschlossen, weshalb es vernünftig ist, den Fallback überall eingeschaltet zu lassen und nicht nur in den Vorlagen, die man von Hand geprüft hat
Eine Folge unter der Abort-Richtlinie: Trifft die Messung auf ein nicht auflösbares Zeichen, gibt GetTextWidth 0 zurück und setzt Fehler 521. Layout-Code, der durch eine Breite teilt oder damit eine Zelle bemisst, sollte das prüfen, bevor er mit der Zahl rechnet
Fallback-Schriftschnitte werden nur eingebettet, wenn sie tatsächlich etwas zeichnen. Ein Schnitt in der Kette, der nie einen Cluster aufgelöst hat, trägt nichts zur Datei bei, und ein Schnitt, der es tat, wird als Subset der von ihm gezeichneten Glyphen eingebettet. Ein Dokument mit einem chinesischen Zeichen unter 5.000 lateinischen trägt eine Han-Glyphe, keinen CJK-Schriftschnitt von mehreren Megabytes; wie dieses Subset gebaut wird, beschreibt Dateigrößenoptimierung und Font-Subsetting. Deshalb ist eine lange Kette, die jedes bediente Locale abdeckt, günstig zu konfigurieren, und jedes PDF zahlt nur für das, was es verwendet hat. Dateien, die anderswo erzeugt wurden und Schriftarten referenzieren, die sie nie eingebettet haben, sind eine andere Reparatur, beschrieben in Einbetten fehlender Schriftarten in ein bestehendes PDF
Der Ausrollvorbehalt ist leicht zu übersehen. Fallback löst gegen die Schriftschnitte auf, die auf der Maschine installiert sind, auf der Ihr Code läuft, und eine Entwickler-Workstation mit voller Office-Installation hat weit mehr davon als ein reduziertes Server-Image oder ein Container. Fehlt Yu Gothic oder Microsoft YaHei, hat die Kette nichts, worauf sie zurückfallen kann. Lassen Sie auf dem Ziel-Server ein Dokument mit einem Han-Namen, einem Hangul-Namen und einem Emoji laufen und lesen Sie den JSON-Report: Ein leeres events-Array dort sagt Ihnen mehr als jeder Test auf Ihrem eigenen Desktop. Liefern Sie die Schriftarten aus, auf die Sie angewiesen sind, und prüfen Sie, dass deren Lizenzen Einbettung erlauben
Dieselbe Fallback-Kette, dieselbe Missing-Glyph-Richtlinie und derselbe Bericht sind über die DLL- und ActiveX-Ausgaben erreichbar, also konfigurieren C#-, C++- oder Skript-Aufrufer sie mit denselben Aufrufen. Referenzdokumentation und Downloads finden sich auf der PDF Library for Delphi Produktseite