Набор шаблонов счетов в Arial печатает «Invoice for» — и всё. Вызов текста вернул 1, файл валиден, а при извлечении текста не хватает десяти символов: все ханьские знаки в 北京示例科技有限公司 исчезли, потому что в Arial их нет. Автоматический fallback шрифтов в PDF Library for Delphi включён по умолчанию и тянет такие символы из установленных начертаний, AddFontFallback задаёт собственный порядок поиска, а политика отсутствующих глифов с JSON-отчётом разбирается с тем, чего не нарисует ни одно начертание
Тихая часть — вот что делает это дорогим. PDF с пустым местом там, где должно быть имя стороны, проходит любую структурную проверку, открывается в любом просмотрщике и обычно замечается клиентом, а не вашим тестовым набором
Почему неподдерживаемый текст исчезает, а не вызывает ошибку?
В PDF нет понятия шрифта, отказывающегося от символа, поэтому отсутствующий глиф — не ошибка на уровне файла. Простой шрифт сопоставляет однобайтовые коды именам глифов через кодировку; составной шрифт сопоставляет коды через CMap идентификаторам CID и затем индексам глифов. Запросите у начертания то, чего в нём нет, — и вы попадёте на нулевой индекс глифа, .notdef, который ISO 32000-1 §9.7.6.3 считает стандартным исходом для неопределённых символов. Большинство начертаний рисуют .notdef как ничего; некоторые — как пустой прямоугольник
В любом случае поток содержимого корректен и страница рендерится. Ничто в спецификации не обязывает производителя проверять покрытие перед записью текстового оператора, поэтому генератор, пропускающий проверку, выдаёт конформный файл, в котором содержимое тихо потеряно. Именно поэтому fallback и отчёт о недостающих глифах поставляются вместе: устранить то, что можно устранить, — половина работы; сообщить об остальном — вторая, и на наш взгляд более важная для всего, на чём стоит чьё-то имя или сумма
Включение цепочки fallback в PDF Library for Delphi
Fallback включается только когда выбранный шрифт действительно не содержит какой-то символ строки, поэтому чисто латинский текст идёт обычным путём и ничего не стоит. У нового экземпляра TPDFlib автоматический fallback уже включён, так что коду отрисовки не нужен ни один дополнительный вызов:
var
Lib: TPDFlib;
begin
Lib := TPDFlib.Create;
try
// Автоматический fallback включён по умолчанию: эмодзи, кана,
// хангыль, ханьские знаки и символы ищутся во встроенной таблице кандидатов
Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);
Lib.AddTrueTypeFont('Arial', 2); // 2 = встроить подмножеством
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;
При включённом автоматическом fallback библиотека подбирает кандидатов по письменности каждого неразрешённого символа. Таблица фиксированная и ориентирована на Windows: эмодзи и пиктограммы пробуют Segoe UI Emoji, затем Segoe UI Symbol, затем Arial Unicode MS; кана сначала пробует Yu Gothic; хангыль — Malgun Gothic; объединённый блок ханьских знаков — Microsoft YaHei, затем Microsoft JhengHei, Yu Gothic, Malgun Gothic и SimSun; математические и технические символы уходят в Segoe UI Symbol и Cambria Math. Всё остальное проваливается в широкий список, начинающийся с Nirmala UI и Segoe UI
Начертания, зарегистрированные через AddFontFallback, пробуются раньше той встроенной таблицы, в порядке добавления. SetAutomaticFontFallback(0) выключает только встроенную таблицу: явная цепочка остаётся активной — это настройка для случая, когда вывод должен использовать только одобренные вами начертания и ничего больше. AddFontFallback игнорирует имя, уже попавшее в список, и возвращает его позицию с единицы, а ClearFontFallbacks, RemoveFontFallback и GetFontFallbackCount позволяют пересобрать цепочку между документами
Ловушка унификации ханьских знаков: кто побеждает общие символы?
Китайский, японский и корейский делят большинство ханьских иероглифов Unicode, но каждая локаль ждёт для многих из них разные начертания. Кодовая точка 直 или 骨 одна и та же в токийском и пекинском адресе; форма, которую ждёт носитель языка, — нет. Цепочка fallback отвечает только на вопрос «какое установленное начертание имеет глиф для этой кодовой точки», и он есть у каждого CJK-начертания, поэтому побеждает общие символы то, которое идёт первым
Автоматическая таблица ставит Microsoft YaHei первым для ханьских знаков. Для упрощённого китайского это хорошо, для японского — плохо. Японский адрес в том счёте выходит с каной, нарисованной Yu Gothic (кана отправляет поиск сначала в японское начертание), и кандзи, нарисованными YaHei с китайскими формами, — всё в одной строке. Ничего не пропало, отчёт пуст, а японский читатель сразу видит, что что-то не так
Наша рекомендация — перестать полагаться на автоматический порядок для ханьских знаков и строить явную цепочку из локали документа. Вы её обычно и так знаете — из записи о клиенте или языка шаблона:
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');
// Эмодзи, символы и письменности, не покрытые выше, всё ещё идут
// через встроенных кандидатов; передайте здесь 0, чтобы запретить это
Lib.SetAutomaticFontFallback(1);
end;
Вызывайте один раз на документ, до первого DrawText. Порядок внутри явного списка значит то же самое: побеждает первое начертание, покрывшее символ, поэтому пан-юникодное начертание вроде Arial Unicode MS принадлежит концу списка, если вообще ему принадлежит. Поставьте его первым — и оно нарисует почти всё, а тщательно подобранные начертания для конкретных письменностей не будут опрошены никогда
Fallback работает целыми кластерами
PDF Library for Delphi решает fallback на уровне графемных кластеров, поэтому один кластер всегда рисуется одним начертанием. Слог деванагари, эмодзи с модификатором тона кожи, базовая буква с диакритическими знаками — каждый из них представляет собой одну единицу на экране, и решения о шейпинге внутри него приходят из таблиц одного конкретного шрифта. Половина кластера от Arial и половина от резервного начертания положили бы на страницу глиф, который формально присутствует, но визуально сломан — а это, пожалуй, хуже пустоты
Выбранный шрифт сначала шейпит строку. Искать другое начертание отправляются только кластеры, вернувшиеся нулевым глифом, а соседние кластеры, разрешившиеся в одно начертание, рисуются вместе одним прогоном, поэтому китайское имя из десяти знаков становится единым прогоном YaHei, а не десятью отдельными переключениями шрифта. Порядок справа налево тоже сохраняется: fallback-прогон внутри арабского или иврита сидит там, куда его поставил двунаправленный алгоритм. Тем же шейпинговым механизмом движется вертикальное письмо для японского и китайского
Останавливать ли документ из-за отсутствующего глифа?
Это зависит от назначения документа, и PDF Library for Delphi даёт выбрать через SetMissingGlyphPolicy. PDF_MISSING_GLYPH_REPORT — значение по умолчанию: операция текста идёт вперёд, символы, которых не может нарисовать ни одно начертание, отбрасываются из вывода, и каждый фиксируется. PDF_MISSING_GLYPH_ABORT отклоняет всю операцию текста до записи чего-либо на страницу, DrawText возвращает 0, а код ошибки — 521 (PDFLIB_ERROR_MISSING_GLYPH)
Для внутренних пакетных отчётов берите политику report и логируйте пробелы: чуть неполный отчёт сегодня лучше, чем никакого отчёта. Для договоров, счетов, сертификатов и всего, что несёт чьё-то имя или название компании, берите abort. Отброшенный символ в имени стороны — дефект, который вы хотите найти в собственном конвейере, а поскольку abort происходит до записи, на странице не остаётся недорисованной строки
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; // чтение также сбрасывает его в 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;
Обратите внимание на локальную переменную. LastErrorCode очищает себя при чтении, поэтому код, проверяющий Lib.LastErrorCode = 0 в одном месте и логирующий Lib.LastErrorCode в другом, запишет в лог 0. Читайте один раз и сохраняйте значение
Каждое событие отчёта несёт страницу, индекс UTF-16 внутри строки, кодовую точку в десятичном виде и в форме U+XXXX, выбранный шрифт, его тип и вызов API, на котором случилась проблема. С этим тикет поддержки называет точный символ, а не описывает симптом. Флаг valid равен true, только когда событий не записано ни одного, что делает его дешёвой проверкой в пакетном задании
Библиотека хранит 256 самых свежих событий и выбрасывает более старые, поэтому документ, полный неотрисовываемого текста, не может превратить диагностику в проблему с памятью. События копятся между документами на одном экземпляре TPDFlib; вызывайте ClearMissingGlyphReport перед каждым документом, если хотите один отчёт на файл, или различайте их по полю documentIndex
Прерывать на буквах, терпеть декор
Одна политика на весь документ иногда слишком груба. Транспортная этикетка может нести декоративное эмодзи рядом с именем получателя, и вам лучше потерять эмодзи, чем отклонить этикетку. Событие OnMissingGlyph срабатывает для каждого символа, которого не смогло нарисовать ни одно начертание в цепочке, получает политику как действие по умолчанию и может переопределить её по кодовой точке:
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
// Пиктограммы и дингбаты — декор: отбрасываем и записываем
if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
((CodePoint >= $2600) and (CodePoint <= $27BF)) then
Action := PDF_MISSING_GLYPH_REPORT
else
Action := PDF_MISSING_GLYPH_ABORT; // буквы и цифры пропадать не должны
end;
// Подключение
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;
Событие срабатывает после того, как fallback получил свой шанс, поэтому видит только символы, действительно неразрешимые на этой машине. Каждый из них всё равно попадает в JSON-отчёт, какое бы действие ни выбрал обработчик
Измерение, встраивание и развёртывание
GetTextWidth проходит через те же решения fallback кластер за кластером, что и DrawText. Звучит очевидно, но именно здесь ошибаются самодельные слои fallback: они патчат вызов отрисовки, оставляя измерение на основном шрифте, и тогда каждая сумма с выравниванием вправо и каждая колонка таблицы вычисляется из ширин, не совпадающих с тем, что окажется на странице. Здесь строка, измеренная перед отрисовкой, занимает ту ширину, на которую была измерена, включая резервные прогоны, — именно это делает разумным держать fallback включённым везде, а не только в шаблонах, которые вы проверили руками
Одно следствие политики abort: когда измерение наталкивается на неразрешимый символ, GetTextWidth возвращает 0 и ставит ошибку 521. Коду раскладки, делящему на ширину или использующему её для размера ячейки, стоит проверить это до использования числа
Резервные начертания встраиваются, только если нарисовали что-то. Начертание в цепочке, ни разу не разрешившее кластер, ничего не добавляет в файл, а то, что разрешило, встраивается подмножеством нарисованных глифов. Документ с одним китайским знаком среди 5 000 латинских несёт один ханьский глиф, а не CJK-шрифт на несколько мегабайт; как строится это подмножество — в статье оптимизация размера файла и субсеттинг шрифтов. Именно поэтому длинная цепочка, покрывающая все обслуживаемые вами локали, дешёвая в настройке, и каждый PDF платит только за то, что использовал. Файлы, произведённые где-то ещё и ссылающиеся на шрифты, которые они так и не встроили, — другой ремонт, описанный в статье встраивание недостающих шрифтов в существующий PDF
Оговорку про развёртывание легко пропустить. Fallback разрешается по шрифтам, установленным на машине, где выполняется ваш код, а рабочая станция разработчика с полной установкой Office несёт куда больше шрифтов, чем урезанный серверный образ или контейнер. Если Yu Gothic или Microsoft YaHei там нет, цепочке не на что переключиться. Прогоните один документ с ханьским именем, хангыльным именем и эмодзи на целевом сервере и прочитайте JSON-отчёт: пустой массив events скажет больше, чем любой тест на вашем собственном десктопе. Поставляйте шрифты, от которых зависите, и проверьте, что их лицензии разрешают встраивание
Та же цепочка fallback, политика отсутствующих глифов и отчёт доступны в изданиях DLL и ActiveX, поэтому вызывающий код на C#, C++ или скриптах настраивает их теми же вызовами. Справочная документация и загрузки — на странице продукта PDF Library for Delphi