В PDFium Component чтение аннотации через TPdf.Annotation[] и запись записи обратно, когда ничего не изменилось, не пишет ничего нового: геттер отчитывается только о внешности, которую реально прочитал, поэтому аннотация, несущая лишь /N, возвращается лишь с /N. Эту деталь стоит понимать, потому что сторона чтения, отчитывающая лишнего, добавляет пустые записи /R и /D в словарь внешности /AP, валидаторы PDF/A такой словарь отвергают, а типичный триггер — правка, задуманная сделать файл более соответствующим стандарту, а не менее
Что ломается, когда вы записываете аннотацию обратно нетронутой?
Короткий ответ: если сторона чтения отчитывает лишнего, аннотация обзаводится потоками внешности, которых у неё никогда не было, и файл, проходивший валидацию PDF/A до вашей правки, проваливает её после. Типовой сценарий выглядит так. Приходит клиентский архив с square- и text-аннотациями без флага Print; PDF/A требует, чтобы каждая аннотация печаталась, поэтому вы обходите страницы в цикле, добавляете afPrint и записываете каждую запись обратно. Ничто в этом коде не трогает внешности. Запись из TPdf.Annotation[] — это TPdfAnnotation, а SetAnnotationData пишет каждое поле, чей сентинел Has* взведён, — ровно так задуманы пары HasContents / ContentsText. Ловушка — геттер, ставящий HasAppearanceRollover и HasAppearanceDown в True с пустыми строками для несуществующих режимов; сеттер тогда послушно пишет два пустых потока. Геттер PDFium Component отчитывается только о прочитанном, поэтому цикл ниже пишет обратно лишь те внешности, что были у источника:
procedure MarkAnnotationsPrintable(const FileName: string);
var
Pdf: TPdf;
PageNo, I: Integer;
A: TPdfAnnotation;
begin
Pdf := TPdf.Create(nil);
try
Pdf.FileName := FileName;
Pdf.Active := True;
for PageNo := 1 to Pdf.PageCount do
begin
Pdf.PageNumber := PageNo;
for I := 0 to Pdf.AnnotationCount - 1 do
begin
A := Pdf.Annotation[I];
if not (afPrint in A.Flags) then
begin
A.Flags := A.Flags + [afPrint] - [afHidden, afInvisible, afNoView];
// Геттер отчитывается только о прочитанных внешностях, поэтому источник
// с одним лишь /AP/N записывается обратно с одним лишь /AP/N
Pdf.Annotation[I] := A;
end;
end;
end;
Pdf.SaveAs(ChangeFileExt(FileName, '.printable.pdf'));
finally
Pdf.Free;
end;
end;
ISO 32000-1 §12.5.5 определяет словарь внешности тремя записями: /N для нормальной внешности, /R для rollover и /D для нажатия. /R и /D опциональны, и когда их нет, вьюер откатывается к /N. Пустой поток /R — не отсутствие, однако. Это валидный поток, который ничего не рисует, поэтому вьюер, чтящий rollover-внешности, показывает пустой прямоугольник в момент, когда указатель попадает на аннотацию. PDF/A строже: ISO 19005-1 (с Corrigendum 2) и ISO 19005-2 / 19005-3 допускают в словаре внешности аннотации только /N. veraPDF рапортует такой файл по правилу 6.5.3-4 для PDF/A-1 и 6.3.3-2 для PDF/A-2 и PDF/A-3, а встроенный TPdf.ValidatePdfA числит его как pvaiAnnotationApDictViolation. Правка, добавившая флаг Print ради одной клаузы стандарта, может сломать другую
Почему FPDFAnnot_GetAP возвращает 2 для отсутствующей внешности?
PDFium никогда не возвращает ноль из FPDFAnnot_GetAP, даже когда запрошенный поток внешности не существует. Функция следует обычному двухвызовному паттерну PDFium: передаёте nil-буфер, чтобы получить требуемый размер в байтах, аллоцируете, затем зовёте снова для копирования текста UTF-16LE. Размер всегда включает UTF-16-терминатор, поэтому отсутствующий поток репортит 2 байта — пустая строка плюс её терминатор. Очевидный гейт ByteLength >= SizeOf(FPDF_WCHAR) — проверка, которую проходит каждый вызов, поэтому построенный на ней геттер ставит все три флага HasAppearance* в True для любой аннотации хоть с какой-то внешностью. Round-trip через запись затем просит FPDFAnnot_SetAP сохранить пустую строку для каждого режима, и PDFium создаёт поток, чтобы её вместить. Ни исключения, ни предупреждения, и видимая страница выглядит идентично — потому эта ошибка и всплывает в валидаторе PDF/A, а не во вьюере
Как PDFium Component решает, что внешность существует
ReadAppearance — хелпер внутри GetPageAnnotation, заполняющий AppearanceNormal, AppearanceRollover и AppearanceDown, — считает результат содержимым, только когда тот несёт хотя бы один символ сверх терминатора. Первый вызов обязан вернуть больше SizeOf(FPDF_WCHAR) байтов и чётное число байтов, поскольку нечётная длина не может быть UTF-16. Второй вызов, который действительно копирует текст, валидируется повторно: возвращённая длина 2 или меньше, либо больше выделенного буфера, сбрасывает HasValue в False и оставляет строку пустой. На стороне записи SetAnnotationData зовёт FPDFAnnot_SetAP только для режимов с взведённым флагом HasAppearance*, так что запись, прочитанная из аннотации с одним лишь /N, пишет обратно только /N
Отсутствующие и пустые потоки выглядят одинаково, поэтому геттер остаётся консервативным
Нативный API не отличит отсутствующий поток внешности от существующего, но пустого, и PDFium Component не притворяется обратным. Оба случая возвращают те же 2 байта из FPDFAnnot_GetAP, поэтому оба читаются как HasAppearanceRollover = False с пустым AppearanceRollover. Отсюда два следствия, под которые стоит проектировать. Первое: False-сентинел означает «содержимое не прочитано, поэтому запись обратно не тронет этот режим», а не «ключа /R нет в словаре». Второе: запись не может детектировать пустой поток, уже лежащий в файле: документ, уже несущий пустой поток — чем бы его ни написал, — читается как чистый, и запись записи обратно его ни чинит, ни усугубляет. Чтобы найти такие файлы, нужна байтовая проверка — для того и служат TPdf.ValidatePdfA и workflow предпечатной валидации PDF/A с PDFium Component
Как нарочно очистить внешность?
Вы взводите сентинел явно и передаёте пустую строку; сеттер её пишет. Блокировка пустых строк в SetAnnotationData была бы тупым способом избежать случайных потоков, но она же сломала бы вызывающих, очищающих внешность намеренно, — тот же контракт, которому следуют HasContents и HasAuthor для текста. Поэтому осторожность живёт в геттере, а сеттер делает то, о чём просит вызывающий:
// Заменяем rollover-внешность, затем очищаем снова
A := Pdf.Annotation[0];
A.HasAppearanceRollover := True;
A.AppearanceRollover := 'q Q';
Pdf.Annotation[0] := A;
A := Pdf.Annotation[0];
// A.HasAppearanceRollover равно True, и текст проходит round-trip как 'q Q'
A.HasAppearanceRollover := True; // заново явно подтверждаем намерение
A.AppearanceRollover := ''; // нарочно пишем пустой поток
Pdf.Annotation[0] := A;
A := Pdf.Annotation[0];
// Читается обратно как HasAppearanceRollover = False с пустой строкой:
// пустой поток и отсутствующий здесь неразличимы
Имейте в виду: нарочно опустошённый /R или /D всё ещё считается лишним ключом по приведённым выше правилам PDF/A. Если цель — архивный профиль, единственная валидная форма — записать непустой /N и не трогать два других режима. Любой workflow, перекладывающий аннотации между документами, вроде экспорта и импорта XFDF с PDFium Component, должен следовать тому же правилу: копируйте режимы, которые реально были у источника, и оставляйте остальные сентинелы в False
Паттерн read-modify-write, который остаётся безопасным для PDF/A
Оставьте сентинелы внешности ровно такими, как их вернул геттер, и валидируйте сохранённый файл до отгрузки. Поскольку лежалый пустой поток читается как отсутствующий, шаг проверки обязан смотреть на сериализованный документ, а не на запись, — а это дёшево гонять после каждой партии:
uses
PDFium, FPdfPdfa; // FPdfPdfa объявляет TPdfAValidationIssue
function AnnotationAppearancesAreClean(Pdf: TPdf): Boolean;
var
Report: TPdfAValidationResult;
begin
// Валидирует документ, загруженный в Pdf сейчас, включая правки,
// сделанные через Pdf.Annotation[] с момента открытия
Report := Pdf.ValidatePdfA;
Result := not (pvaiAnnotationApDictViolation in Report.Issues);
end;
Та же дисциплина касается любой панели, перекрашивающей или аннотирующей страницы для ревью, — workflow, разобранный в статье о построении workflow аннотационного ревью в Delphi с PDFium Component: запись — это снимок того, что движок смог прочитать, и сентинел, который вы не ставили сами, должен уезжать обратно нетронутым. Полный аннотационный API, PDF/A preflight и нативный движок PDFium едут вместе в PDFium Component для Delphi, C++Builder и Lazarus