Впишите имя в поле Applicant на странице 1 свежесобранного пакета анкеты, нажмите Tab — и во многих вьюверах поле Applicant на странице 6 заполнится тем же текстом. Никто эти два элемента управления не связывал. Части 1 и 3 пакета писали разные люди, оба назвали поле верхнего уровня Applicant, а PDF-форма идентифицирует поле по полностью квалифицированному имени. Два поля с одним именем — по мнению формата файла — одно поле, нарисованное дважды
Решение — решить, что общее имя должно означать, ещё до слияния: отвергнуть его, сохранить намеренно или переименовать новичка. Решать потом куда труднее, чем кажется
Что ISO 32000 понимает под именем поля
Имя поля — это идентичность, и спецификация говорит об этом прямо. ISO 32000-1, §12.7.3.2 строит полностью квалифицированное имя из частичного имени (записи T) поля и каждого из его предков, соединённых точками. Тот же раздел допускает, что несколько словарей полей делят одно полностью квалифицированное имя, и описывает их как разные представления одного и того же нижележащего поля, которые должны различаться лишь внешним видом. Конкатенация массивов Fields двух независимо написанных форм порождает ровно такую конструкцию — совершенно случайно
Ущерб зависит от того, что хранили столкнувшиеся поля. Date, означавший дату рождения на одной форме и дату подписания на другой, теперь имеет единственный слот значения, и какое бы значение вьювер ни выбрал, оно окажется в обоих местах. Total на листе расходов и Total на форме вклада разойдутся в момент, когда любой из них будет вычислен. Поля подписи — худший случай: два виджета подписи на разных страницах, одно имя, и нет чистого ответа, какой именно виджет подписант реально утвердил
Регистр тоже имеет значение. Частичные имена — текстовые строки, и ничто в спецификации их не свёртывает, поэтому Total и total — два разных поля. Проверка коллизий, приводящая имена к нижнему регистру перед сравнением, рапортует о несуществующих конфликтах, а при политике переименования переименовывает поля, которых никто не должен был касаться
Проверка имён до того, как что-либо сдвинется
PDF Library for Delphi разбирается с коллизией в MergeDocumentEx(DocumentID, DuplicateFieldStrategy), которая сливает документ, идентифицированный DocumentID, в текущий выбранный документ и улаживает всякий конфликт имён до того, как хоть один объект будет перенумерован. Стратегия — значение TPDFlibDuplicateFieldStrategy: dfsReject, dfsMerge или dfsAutoNumber. Простая MergeDocument по-прежнему конкатенирует два корневых массива полей без изменений — и это правильный выбор, когда обе формы ваши и вы знаете, что их имена не пересекаются
Порядок — весь дизайн. Слияние обязано сдвинуть номера объектов входящего документа, чтобы они не столкнулись с номерами целевого, вшить его страницы в дерево страниц целевого и дописать его поля в форму. Если коллизия всплывает лишь после этих шагов, отказ уже не бесплатен — целевой уже поглотил страницы, объекты источника несут номера, с которыми не начинал ни один файл, а у вызывающего нет состояния, к которому можно откатиться, кроме перезагрузки обоих файлов с диска. MergeDocumentEx сначала собирает имена полей верхнего уровня обоих документов в упорядоченное, чувствительное к регистру множество и применяет стратегию к этому множеству. При dfsReject коллизия заставляет вызов вернуть 0 с LastErrorCode, равным 705, и оба документа остаются ровно такими, как были загружены: сразу после отказа можно прочитать значение поля из документа-источника и получить исходный текст
Само сканирование дёшево. При n именах в целевом документе и m в исходном сортировка их в одно множество стоит порядка (n + m) log(n + m) сравнений, так что пакет из нескольких сотен полей не добавляет ничего заметного на фоне разбора файлов
Три свойства сканирования проявляются в реальных пакетах форм:
- Сравниваются только поля верхнего уровня. В иерархической форме это частичное имя родителя, поэтому две формы, у каждой из которых есть родитель
applicant, сталкиваются, даже если их дети различаются, а автонумерация переименовывает родителя: входящие дети тогда читаются какapplicant_2.nameиapplicant_2.address - Входящие имена добавляются в множество по мере проверки. Документ-источник, который уже несёт два поля верхнего уровня с одинаковым именем, срабатывает стратегию на втором из них, даже когда в целевом нет ни одного поля с таким именем
- Поля с пустым частичным именем пропускаются, а когда ни в одном из документов нет AcroForm, сравнивать нечего, и слияние идёт вперёд при любой стратегии
У стороны загрузки есть своя ловушка. LoadFromFile добавляет новый документ в библиотеку и выбирает его, поэтому хранить нужно идентификатор, который SelectedDocument возвращает после каждой загрузки. Схватите его до загрузки — и вы держите другой документ, не тот, в который, как вам кажется, сливаете
uses
SysUtils, PDFlibrary;
procedure BuildPack(const Part1, Part2, OutFile: WideString);
var
Lib: TPDFlib;
TargetDoc, SourceDoc: Integer;
begin
Lib := TPDFlib.Create;
try
if Lib.LoadFromFile(Part1, '') = 0 then
raise Exception.CreateFmt('Cannot load %s', [Part1]);
TargetDoc := Lib.SelectedDocument; // читать после загрузки, а не до
if Lib.LoadFromFile(Part2, '') = 0 then
raise Exception.CreateFmt('Cannot load %s', [Part2]);
SourceDoc := Lib.SelectedDocument;
Lib.SelectDocument(TargetDoc); // выбранный документ принимает слияние
if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
begin
if Lib.LastErrorCode <> 705 then
raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
// Дубликаты имён верхнего уровня: оба документа нетронуты,
// поэтому SourceDoc можно сразу отдать под вторую попытку
WriteLn('Duplicate field names in ', Part2, ', retrying with auto-numbering');
if Lib.MergeDocumentEx(SourceDoc, dfsAutoNumber) = 0 then
raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
end;
Lib.SaveToFile(OutFile);
finally
Lib.Free;
end;
end;
Сначала строго, потом снисходительно. Эта двухшаговая форма работает лишь потому, что отказ оставляет SourceDoc загруженным и целым; при слиянии, падающем на середине, запасная ветка начинала бы с перезагрузки обоих файлов. Проверка именно 705 тоже важна: недействительный идентификатор документа или стратегия вне диапазона валят вызов с другим кодом, и повторная попытка с другой стратегией ни то, ни другое не починит
Выбор стратегии: отклонить, разделить или перенумеровать
Для автоматических конвейеров сделайте dfsReject выбором по умолчанию и относитесь к 705 как к заявке тому, кому принадлежат исходные формы. Переименовать поле выше по цепочке один раз дешевле, чем через месяцы обнаружить, что сопоставление экспорта тихо перестало биться, потому что слияние изобрело Total_2. Автоматические стратегии заслуживают своё место, когда человек посмотрел на формы и решил, что общие имена означают
dfsMerge намеренно сохраняет общее имя. Прежде чем что-либо дописывается, значение и значение по умолчанию целевого поля копируются во входящее, поэтому слитый файл стартует согласованным, а вьювер, группирующий виджеты по имени, видит одно логическое поле с одним значением. Два словаря полей остаются отдельными объектами, каждый хранит собственную страницу, внешний вид и действия. Сворачивать их в один словарь — значит выбрасывать форматирование и поведение, принадлежащие входящей форме, и эта сделка не стоит косметического упрощения
dfsAutoNumber переименовывает входящие дубликаты, дописывая числовой суффикс — начиная с _2 и беря первый свободный. Если целевой уже имеет Shared и Shared_2, новичок станет Shared_3. Результат зависит только от присутствующих имён и никогда от номеров объектов, поэтому слияние одной и той же пары файлов дважды даёт одни и те же имена оба раза — свойство, на которое опираются нижележащие импорты FDF и сопоставления с базой данных
Выбор между двумя автоматическими стратегиями сводится к одному вопросу: должно ли заполнение одного элемента управления заполнять и другой? Для имени подписанта, повторяющегося на каждой части пакета, — да, и dfsMerge подходит. Для итога, вычисляемого на каждой форме по-разному, — нет. Берите там dfsAutoNumber, а лучше переименуйте поле в исходной форме, чтобы суффикс вообще не появлялся
Что содержит слитая форма после этого?
Возьмите целевой документ с текстовым полем верхнего уровня Shared, хранящим «Target value», и источник с собственным Shared. После dfsMerge FormFieldCount насчитает два поля, оба названные Shared, оба сообщающие «Target value». После dfsAutoNumber тот же вход даёт Shared и Shared_2, а входящее поле хранит то значение, которое у него было в файле-источнике
У результата dfsMerge есть острый край, и сидит он в вашем собственном коде заполнения. FindFormFieldByTitle возвращает первый индекс с совпавшим заголовком, а SetFormFieldValue пишет ровно в одно поле. Подпрограмма, которая находит Shared один раз и устанавливает его, обновит копию целевого и оставит входящую копию со значением, полученным при слиянии. Сохранённый файл теперь содержит два поля с одним именем и двумя разными значениями, а какое покажет вьювер — решать вьюверу. Пишите во все совпадения:
// Устанавливает каждое поле с заголовком Title; возвращает, сколько записано.
// После слияния dfsMerge одно логическое поле может сидеть на нескольких индексах
function SetAllFieldsNamed(Lib: TPDFlib; const Title, Value: WideString): Integer;
var
I: Integer;
begin
Result := 0;
for I := 1 to Lib.FormFieldCount do
if Lib.GetFormFieldTitle(I) = Title then
begin
if Lib.SetFormFieldValue(I, Value) = 1 then
Inc(Result)
else
WriteLn(Format('Field %d (%s) not written, error %d',
[I, Title, Lib.LastErrorCode])); // поля только для чтения попадают сюда
end;
end;
Прежде чем подключать слитый пакет к потоку данных, выгрузите то, что слияние реально произвело. Двухстрочного цикла достаточно, и он поймает переименованных родителей и суффиксы _2 раньше задания импорта:
for I := 1 to Lib.FormFieldCount do
WriteLn(Format('%3d %-30s %s',
[I, Lib.GetFormFieldTitle(I), Lib.GetFormFieldValue(I)]));
Сборка пакета форм на практике
Успешное слияние поглощает документ-источник. Он удаляется из списка документов библиотеки, поэтому DocumentCount падает на единицу, а старый идентификатор SourceDoc использовать больше нельзя. Слитый документ берёт старшую из двух версий PDF: слияние формы PDF 2.0 в документ 1.7 даёт файл 2.0 — это важно, если нижележащий шаг архивирования ожидает конкретную версию
Порядок слияния решает, чьи имена выживут. Выбранный документ сохраняет все свои имена, а переименования и копирование значений применяются только к входящим полям, поэтому слияние A в B и слияние B в A дают разные автонумерованные результаты. Когда у пакета есть основная форма — та, чьи имена полей ваш бэк-офис уже знает, — сделайте её целевой и сливайте дополнения в неё
Подписывайте последними. Подпись покрывает байты редакции, которую она подписала, а слияние переписывает файл, поэтому часть, подписанная до сборки, больше не несёт подписи, соответствующей документу. Соберите пакет, проверьте список полей, затем накладывайте подписи на готовый файл. Если задача — только сшить страницы, а формы не важны, быстрее пойдёт быстрое слияние PDF со сдвигом байтовых ссылок
Планируйте сторону данных вместе со слиянием. Если значения полей приходят из внешней системы, адресующей поля по имени, уладьте именование до выбора dfsAutoNumber: Shared_2 не совпадёт с сопоставлением, ожидающим Shared. Форматы импорта и экспорта значений охватывает статья о обмене данными форм FDF, XFDF и XFA. Скрипты вычислений и действия, ссылающиеся на поля по имени, страдают от переименования точно так же, а где живут эти ссылки, показывает статья об интерактивных действиях форм и JavaScript
Слияние форм с учётом дубликатов, заполнение полей и цифровое подписание — части одной библиотеки для проектов на Delphi, C++Builder и Free Pascal. Остальное API сборки форм и документов перечислено на странице продукта PDF Library for Delphi