Інтерактивне середовище виконання динамічних віджетів XFA

TXFAWidgetRuntime надає нейтральну до хоста модель взаємодії для динамічних форм XFA без перетворення їх у поля AcroForm або сплощення їхнього вмісту

Середовище виконання надає детерміновані межі та стан віджетів, щоб десктопний, службовий або власний рендерер міг забезпечити власне введення, малювання, доступність і цикл подій

Створення середовища виконання

Створіть середовище виконання безпосередньо з байтів XDP або викличте THotPDF.CreateLoadedXFAWidgetRuntime після завантаження PDF, чий AcroForm містить запис /XFA у вигляді одного потоку або масиву пакетів

var
  Runtime: TXFAWidgetRuntime;
  State: TXFAWidgetState;
begin
  Runtime := PDF.CreateLoadedXFAWidgetRuntime;
  try
    if (Runtime <> nil) and (Runtime.WidgetCount > 0) then
    begin
      State := Runtime.Widgets[0];
      Runtime.FocusWidget(State.ID);
      Runtime.BeginEdit(State.ID);
      Runtime.ReplaceSelection(0, Length(State.Value), 'Updated value');
      if not Runtime.CommitEdit then
        raise Exception.Create(Runtime.LastDiagnostic);
    end;
  finally
    Runtime.Free;
  end;
end;

Фабрика завантаженого документа є лише для читання щодо графа об'єктів PDF і наявних XFAFlattenWarnings; збереження документа зберігає його оригінальні записи /XFA та /NeedsRendering

Модель взаємодії

• FocusWidget і ClearFocus підтримують один сфокусований віджет і публікують упорядковані зворотні виклики фокуса
• BeginEdit, ReplaceSelection, CancelEdit і CommitEdit зберігають текст Unicode, зокрема початкові та кінцеві пробіли
• HitTest зіставляє координати сторінки з верхнім видимим віджетом
• OnWidgetInvalidated, OnLayoutChanged і OnFocusChanged дають хосту змогу оновлювати лише змінений стан

Атомарна валідація та обчислення

Під час фіксації розв'язуються явні прив'язки SOM і поточний контекст даних повторюваних рядків, перш ніж виконуються скрипти валідації та обчислення

Відредаговане значення, обчислені значення, вузли даних, модель віджета, стан фокуса й редагування, попередження та лічильники проходів публікуються разом лише після стабілізації валідації та розкладки

Відхилені скрипти, вичерпані бюджети, недійсні межі вибору UTF-16 і винятки розкладки чи вимірювання хоста відновлюють повний попередній стан і встановлюють LastDiagnostic

Бюджети

TXFAWidgetRuntimeOptions обмежує кількість віджетів, довжину відредагованого значення, проходи обчислення, проходи реперфлоу, операції розкладки, операції скриптів, витрачений час скриптів та інші ресурси FormCalc або JavaScript

Обмеження віджетів застосовується, поки додаються елементи розкладки та фрагменти пагінації, тоді як розпакування завантаженого XFA та збірка пакетів зупиняються на межі введення DOM XFA перед аналізом

MaxLayoutOperations типово дорівнює 200000 і обмежує і прохід документом, і роботу розкладки; глибина розкладки обмежена 128, глибина цілі події та ініціалізації екземплярів — 64, а рекурсивна диспетчеризація подій відхиляється

Обмежені динамічні події

DispatchEvent приймає розділені крапкою з комою буквальні операції у відповідних скриптах подій полів з типами вмісту FormCalc або JavaScript; ці операції розбираються напряму і не потребують JavaScript DLL

row.instanceManager.addInstance(true);
row.instanceManager.removeInstance(0);
target.presence = "hidden";

addInstance додає один екземпляр і приймає true, false, 1 чи 0 як аргумент злиття; пропущений аргумент означає true, а скорочений запис _row.addInstance(1) також приймається

Підтримувана модель прив'язує кожну наявну однойменну групу даних, тож новий екземпляр отримує нову групу даних, ініціалізовану з усталених значень шаблону, за будь-якого аргументу злиття; створення екземпляра не клонує введені значення попереднього рядка

removeInstance використовує цілочисельний індекс з нуля серед однойменних груп даних обраного subform; subform має мати елемент occur з повторюваним максимумом, і обидві операції дотримуються його мінімуму та максимуму, зокрема max="-1"

Мутація екземплярів вимагає неявної іменованої прив'язки набору даних і ASCII-имен даних XML; явна прив'язка через посилання на дані та неоднозначні батьківські контексти відхиляються до публікації транзакції

Цілі розв'язуються через іменовані дочірні вузли шаблону в охоплюючих областях події, зокрема крапкові шляхи та this.parent; менеджер, вкладений у повторювану область, використовує власну групу даних події

presence приймає visible, hidden і invisible на полях шаблону, draw, subform та групах виключення; прихований вміст не займає місця в потоці, тоді як невидимий зберігає своє місце, але пропускається у віджетах і виводі flatten

Зміни presence застосовуються до обраного вузла шаблону, а отже, і до всіх його повторюваних входжень; presence з індексацією окремих екземплярів, inactive, довільні вирази, змінні, умовні конструкції, цикли та інші операції скриптів подій відхиляються

Пакет подій публікує зміни даних, обчислення, розкладку, фокус і стан редагування разом після стабілізації реперфлоу; будь-яка відхилена операція або вичерпаний бюджет вводу, операцій, екземплярів, значень, віджетів, розкладки чи часу відновлює повний попередній стан документа та взаємодії

Видалення рядка зберігає фокус і незавершені редагування для груп даних, що лишилися, навіть коли їхні індекси віджетів змінюються; видалення чи приховування віджета у фокусі скидає фокус і публікує відповідний callback фокуса після успіху

Збереження оновленої форми

SaveToBytes повертає повний оновлений XDP середовища виконання, зокрема змінені набори даних та атрибути presence шаблону; використовуйте ці байти з SetXFADocument під час запису PDF або з HPDFXFAFlatten для оновленого flatten-виводу

Фабрика завантаженого документа створює незалежне середовище виконання, тож події середовища не змінюють автоматично граф об'єктів вихідного PDF

Поточні обмеження

Середовище виконання є однопотоковим об'єктом хоста й не надає GUI, засобів малювання чи загального рушія скриптів подій XFA

Увімкнення та вимкнення фокуса підтримуються безпосередньо, коли відповідний скрипт події відсутній; обмежені операції подій не означають підтримки повного JavaScript, FormCalc, подій життєвого циклу XFA чи окремого DOM форми з перевизначеннями подання для окремих екземплярів

Див. Обмежений XFA FormCalc і JavaScript, DOM пакета XFA та Інтерактивна обробка документів