Szablon faktury złożony krojem Arial drukuje „Invoice for” i potem już nic. Wywołanie tekstu zwróciło 1, plik przeszedł walidację, a ekstrakcja tekstu wypadła o dziesięć znaków za krótka: każdy znak han w 北京示例科技有限公司 zniknął, bo Arial nie ma żadnego z nich. Automatyczny fallback czcionek w PDF Library for Delphi jest domyślnie włączony i ciągnie takie znaki z zainstalowanych krojów, AddFontFallback ustawia twoją własną kolejność przeszukiwania, a polityka brakujących glifów z raportem JSON zajmuje się tym, czego nie narysuje żaden krój
Cicha część jest tym, co czyni to kosztownym. PDF z pustym miejscem tam, gdzie powinno być nazwisko strony, przechodzi każdą kontrolę strukturalną, otwiera się w każdym czytniku i zwykle zostaje zauważony przez klienta, a nie przez twój zestaw testów
Dlaczego nieobsługiwany tekst znika, zamiast zgłosić błąd?
PDF nie zna pojęcia czcionki odmawiającej znaku, więc brakujący glif nie jest błędem na poziomie pliku. Czcionka prosta mapuje kody jednobajtowe na nazwy glifów przez kodowanie; czcionka złożona mapuje kody przez CMap na identyfikatory CID, a potem na indeksy glifów. Poproś krój o coś, czego nie zawiera, i wylądujesz na indeksie glifu zero, .notdef, który ISO 32000-1 §9.7.6.3 traktuje jako standardowy wynik dla niezdefiniowanych znaków. Większość krojów rysuje .notdef jako kompletnie nic. Niektóre rysują pusty prostokąt
Tak czy inaczej strumień treści jest poprawny i strona się renderuje. Nic w specyfikacji nie każe producentowi sprawdzić pokrycia przed zapisem operatora tekstu, więc generator pomijający to sprawdzenie tworzy zgodny ze standardem plik, który po cichu utracił treść. Dlatego fallback i raportowanie należą do siebie. Rozwiązanie tego, co da się rozwiązać, to połowa roboty; powiedzenie ci o reszcie to druga połowa, i w naszym przekonaniu ważniejsza dla wszystkiego, co ma na sobie nazwisko albo kwotę
Włączanie łańcucha fallbacku w PDF Library for Delphi
Fallback wchodzi do gry tylko wtedy, gdy wybrana czcionka faktycznie nie ma w łańcuchu jakiegoś znaku, więc tekst czysto łaciński zostaje na swojej normalnej ścieżce i nic go to nie kosztuje. Nowa instancja TPDFlib ma automatyczny fallback już włączony, więc kod rysujący nie potrzebuje żadnego dodatkowego wywołania:
var
Lib: TPDFlib;
begin
Lib := TPDFlib.Create;
try
// Automatyczny fallback jest domyślnie włączony: emoji, kana, Hangul,
// han i symbole są wyszukiwane we wbudowanej tabeli kandydatów
Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);
Lib.AddTrueTypeFont('Arial', 2); // 2 = osadź jako podzbiór
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;
Przy włączonym automatycznym fallbacku biblioteka wybiera kandydatów według pisma każdego nierozwiązanego znaku. Tabela jest stała i zorientowana na Windows: emoji i piktogramy próbują Segoe UI Emoji, potem Segoe UI Symbol, potem Arial Unicode MS; kana próbuje najpierw Yu Gothic; Hangul próbuje najpierw Malgun Gothic; ujednolicony blok han próbuje Microsoft YaHei, potem Microsoft JhengHei, Yu Gothic, Malgun Gothic i SimSun; symbole matematyczne i techniczne idą do Segoe UI Symbol i Cambria Math. Wszystko inne spada do szerokiej listy, która zaczyna się od Nirmala UI i Segoe UI
Kroje zarejestrowane przez AddFontFallback są próbowane przed tą wbudowaną tabelą, w kolejności dodania. SetAutomaticFontFallback(0) wyłącza tylko wbudowaną tabelę: jawny łańcuch pozostaje aktywny, i to jest ustawienie do wybrania, gdy chcesz, żeby wyjście używało twoich zatwierdzonych krojów i niczego innego. AddFontFallback ignoruje nazwę już obecną na liście i zwraca jej pozycję liczoną od jedynki, a ClearFontFallbacks, RemoveFontFallback i GetFontFallbackCount pozwalają przebudować łańcuch między dokumentami
Pułapka unifikacji han: kto wygrywa współdzielone znaki?
Chiński, japoński i koreański dzielą większość ideogramów han w Unicode, ale każda lokalizacja oczekuje innych kształtów liter dla wielu z nich. Punkt kodowy 直 albo 骨 jest ten sam w adresie tokijskim i pekińskim; kształt, którego oczekuje rodzimy czytelnik, już nie. Łańcuch fallbacku odpowiada tylko na pytanie „który zainstalowany krój ma glif dla tego punktu kodowego”, a ma go każdy krój CJK, więc krój, który przychodzi pierwszy, wygrywa każdy współdzielony znak
Automatyczna tabela stawia Microsoft YaHei na pierwszym miejscu dla han. Dla chińskiego uproszczonego to dobrze, dla japońskiego źle. Japoński adres na tamtej fakturze wychodzi z kaną narysowaną przez Yu Gothic (kana kieruje wyszukiwanie najpierw do japońskiego kroju) i z kanji narysowanymi przez YaHei z chińskimi kształtami, wszystko w jednej linii. Niczego nie brakuje, raport pozostaje pusty, a japoński czytelnik od razu widzi, że coś jest nie tak
Nasza rekomendacja: przestań polegać na automatycznej kolejności dla han i zbuduj jawny łańcuch z lokalizacji dokumentu. Zwykle i tak ją znasz, z rekordu klienta albo z języka szablonu:
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 i każde pismo niepokryte powyżej nadal idą
// przez wbudowanych kandydatów; przekaż tu 0, żeby tego zabronić
Lib.SetAutomaticFontFallback(1);
end;
Wywołaj to raz na dokument, przed pierwszym DrawText. Kolejność wewnątrz jawnej listy znaczy tak samo: wygrywa pierwszy krój, który pokrywa znak, więc krój pan-unicode taki jak Arial Unicode MS należy na koniec, o ile w ogóle. Daj go na początek, a narysuje prawie wszystko, a starannie dobrane kroje dla konkretnych pism nigdy nie zostaną zapytane
Fallback działa na całych klastrach
PDF Library for Delphi rozstrzyga fallback per klaster grafemów, więc jeden klaster jest zawsze rysowany przez jeden krój. Sylaba dewanagari, emoji z modyfikatorem odcienia skóry, litera bazowa z łączącymi się akcentami: każdy z nich to jedna jednostka na ekranie, a decyzje kształtowania wewnątrz niego pochodzą z tabel jednej konkretnej czcionki. Połowa klastra z Arial i połowa z kroju zapasowego postawiłaby na stronie glif technicznie obecny i widocznie zepsuty, co można argumentować jest gorsze niż puste miejsce
Wybrana czcionka najpierw kształtuje łańcuch. Tylko klastry, które wróciły jako glif zero, idą szukać innego kroju, a sąsiednie klastry rozwiązane do tego samego kroju są rysowane razem jako jeden przebieg, więc dziesięcioznakowa chińska nazwa staje się jednym przebiegiem YaHei zamiast dziesięcioma osobnymi przełączeniami czcionek. Kolejność od prawej do lewej też jest zachowana: przebieg fallbacku wewnątrz tekstu arabskiego albo hebrajskiego siedzi tam, gdzie postawił go algorytm dwukierunkowy. Tą samą machinerią kształtowania napędzana jest pisownia pionowa dla języka japońskiego i chińskiego
Czy brakujący glif powinien zatrzymać dokument?
To zależy od tego, po co dokument jest, a PDF Library for Delphi pozwala wybrać przez SetMissingGlyphPolicy. PDF_MISSING_GLYPH_REPORT to wartość domyślna: operacja tekstowa idzie dalej, znaków, których nie narysuje żaden krój, brak w wyjściu, a każdy zostaje odnotowany. PDF_MISSING_GLYPH_ABORT odrzuca całą operację tekstową, zanim cokolwiek trafi na stronę, DrawText zwraca 0, a kod błędu to 521 (PDFLIB_ERROR_MISSING_GLYPH)
Dla wewnętrznych seryjnych raportów weź politykę raportowania i loguj luki; lekko niekompletny raport dziś bije brak raportu. Dla umów, faktur, certyfikatów i wszystkiego innego, co niesie nazwisko osoby albo firmy, weź abort. Pominięty znak w nazwie strony to defekt, który chcesz znaleźć we własnym potoku, a bo abort dzieje się przed zapisem, żadna na wpół narysowana linia nie zostaje na stronie
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; // odczyt go przy okazji zeruje do 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;
Zauważ zmienną lokalną. LastErrorCode czyści sam siebie przy odczycie, więc kod, który sprawdza Lib.LastErrorCode = 0 w jednym miejscu, a potem loguje Lib.LastErrorCode w innym, zaloguje 0. Czytaj raz, trzymaj wartość
Każde zdarzenie raportu niesie stronę, indeks UTF-16 wewnątrz łańcucha, punkt kodowy w postaci dziesiętnej i w formie U+XXXX, wybraną czcionkę, jej typ oraz wywołanie API, które trafiło na problem. Z tym zgłoszenie wsparcia nazywa dokładny znak zamiast opisywać objaw. Flaga valid jest true tylko wtedy, gdy nie odnotowano żadnych zdarzeń, co czyni z niej tanią bramkę w zadaniu seryjnym
Biblioteka trzyma 256 najnowszych zdarzeń i wyrzuca starsze, więc dokument pełny nierenderowalnego tekstu nie zamieni diagnostyki w problem z pamięcią. Zdarzenia akumulują się w obrębie dokumentów na tej samej instancji TPDFlib; wołaj ClearMissingGlyphReport przed każdym dokumentem, jeśli chcesz jeden raport na plik, albo użyj pola documentIndex, by je rozróżnić
Prerywanie na literach, tolerowanie dekoracji
Jedna polityka dla całego dokumentu bywa czasem zbyt tępa. Etykieta wysyłkowa może nieść dekoracyjne emoji obok nazwiska odbiorcy, i raczej stracisz emoji niż odrzucisz etykietę. Zdarzenie OnMissingGlyph odpala się dla każdego znaku, którego nie potrafił narysować żaden krój w łańcuchu, dostaje politykę jako swoją domyślną akcję i może ją nadpisać per punkt kodowy:
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
// Piktogramy i dingbaty to dekoracja: porzuć je i odnotuj
if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
((CodePoint >= $2600) and (CodePoint <= $27BF)) then
Action := PDF_MISSING_GLYPH_REPORT
else
Action := PDF_MISSING_GLYPH_ABORT; // litery i cyfry nie mogą znikać
end;
// Podpięcie
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;
Zdarzenie biegnie po tym, jak fallback dostał swoją szansę, więc widzi tylko znaki, które na tej maszynie są naprawdę nierozwiązywalne. Każdy z nich i tak ląduje w raporcie JSON, jakąkolwiek akcję wybierze handler
Mierzenie, osadzanie i wdrażanie
GetTextWidth przechodzi przez te same decyzje fallbacku klaster po klastrze co DrawText. Brzmi to jak oczywistość, a jest dokładnie tym miejscem, gdzie domowej roboty warstwy fallbacku zwykle się gubią: łatają wywołanie rysujące, zostawiają pomiar na czcionce podstawowej, i każda wyrównana do prawej suma oraz kolumna tabeli liczy się potem z szerokości, które nie zgadzają się z tym, co ląduje na stronie. Tutaj łańcuch zmierzony przed narysowaniem zajmuje szerokość, na jaką został zmierzony, wliczając przebiegi fallbacku, i to sprawia, że rozsądnie jest zostawić fallback włączony wszędzie, a nie tylko w szablonach sprawdzonych ręcznie
Jedna konsekwencja pod polityką abortu: gdy pomiar trafi na nierozwiązywalny znak, GetTextWidth zwraca 0 i ustawia błąd 521. Kod układu, który dzieli przez szerokość albo używa jej do wymiarowania komórki, powinien to sprawdzić, zanim użyje liczby
Kroje zapasowe są osadzane tylko wtedy, gdy coś narysują. Krój w łańcuchu, który nigdy nie rozwiązał żadnego klastra, nie wnosi do pliku niczego, a krój, który rozwiązał, jest osadzany jako podzbiór narysowanych glifów. Dokument z jednym chińskim znakiem wśród 5000 łacińskich niesie jeden glif han, a nie czcionkę CJK kilku megabajtów; optymalizacja rozmiaru pliku i tworzenie podzbiorów czcionek opisuje, jak ten podzbiór powstaje. Dlatego długi łańcuch pokrywający każdą obsługiwaną lokalizację jest tani w konfiguracji, a każdy PDF płaci tylko za to, czego użył. Pliki wytworzone gdzie indziej, które wskazują czcionki, których nigdy nie osadziły, to inna naprawa, opisana w osadzaniu brakujących czcionek w istniejącym pliku PDF
Wdrożeniowe zastrzeżenie łatwo przeoczyć. Fallback rozwiązuje względem czcionek zainstalowanych na maszynie, która odpala twój kod, a stacja robocza dewelopera z pełną instalacją Office ma ich daleko więcej niż okrojony obraz serwera albo kontener. Jeśli Yu Gothic albo Microsoft YaHei tam nie ma, łańcuch nie ma do czego spadać. Odpal jeden dokument z chińską nazwą, koreańską nazwą i emoji na docelowym serwerze i przeczytaj raport JSON: pusta tablica events mówi ci więcej niż jakikolwiek test na twoim własnym biurku. Rozsyłaj czcionki, od których zależysz, i sprawdź, czy ich licencje pozwalają na osadzanie
Ten sam łańcuch fallbacku, polityka brakujących glifów i raport są wystawione przez edycje DLL i ActiveX, więc wywołujący z C#, C++ albo skryptów konfigurują je tymi samymi wywołaniami. Dokumentacja referencyjna i pobrania są na stronie produktu PDF Library for Delphi