بيئة تشغيل widgets XFA الديناميكي التفاعلية

TXFAWidgetRuntime provides a host-neutral interaction model for dynamic XFA forms without converting them into AcroForm fields or flattening their content

بيئة التشغيل تُتيح حدود widgets وحالتها حتميتين فيستطيع عارض سطح مكتب أو خدمة أو مخصص تزويد إدخاله ورسمه وإتاحته وحلقة أحداثه الخاصة

أنشئ بيئة تشغيل

Create the runtime directly from XDP bytes or call THotPDF.CreateLoadedXFAWidgetRuntime after loading a PDF whose AcroForm contains a single-stream or packet-array /XFA entry

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;

The loaded-document factory is read-only with respect to the PDF object graph and existing XFAFlattenWarnings; saving the document retains its original /XFA and /NeedsRendering entries

نموذج التفاعل

التزامات التفاعل تزامن القيم العددية الأصلية القائمة في الأسماء البديلة المخفية وغير المرئية، بما يشمل نطاقات بيانات متكررة فعلية وتراجعًا مطابقًا للبايت

التحقق والحساب الذريان

الالتزام يحل روابط SOM الصريحة وسياق بيانات الصف المتكرر الحالي قبل تشغيل سكربتات validate وcalculate

القيمة المحرَّرة والقيم المحسوبة وعقد البيانات ونموذج widget وحالة التركيز والتحرير والتحذيرات وعدادات الجولات تنشر معًا فقط بعد استقرار التحقق والتخطيط

Rejected scripts, exhausted budgets, invalid UTF-16 selection boundaries, and layout or host-measurement exceptions restore the complete previous state and set LastDiagnostic

الميزانيات

TXFAWidgetRuntimeOptions limits widget count, edited value length, calculation passes, reflow passes, layout operations, script operations, elapsed script time, and other FormCalc or JavaScript resources

سقف widgets ينطبق أثناء إلحاق عناصر التخطيط وشظايا الترقيم، بينما يتوقف فك ضغط XFA المحملة وتجميع الحزمة عند حد إدخال DOM لـ XFA قبل التحليل

MaxLayoutOperations defaults to 200000 and bounds both the document walk and layout work; layout depth is limited to 128, event target and instance-initialization depth to 64, and recursive event dispatch is rejected

أحداث ديناميكية حرفية افتراضية

DispatchEvent accepts semicolon-separated literal operations in matching field event scripts with FormCalc or JavaScript content types; these operations are parsed directly and do not require a JavaScript DLL

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

addInstance appends one instance and accepts true, false, 1, or 0 as its merge argument; an omitted argument uses true, and the shorthand _row.addInstance(1) is also accepted

النموذج المدعوم يربط كل مجموعة بيانات بنفس الاسم قائمةً فتتلقى النسخة الجديدة مجموعة بيانات جديدة مهيأةً من افتراضيات القالب لأي وسيط merge؛ وإنشاء النسخة لا يستنسخ قيم الصف السابق المدخلة

removeInstance uses a zero-based integer index among the selected subform's same-name data groups; the subform must have an occur element with a repeatable maximum, and both operations enforce its minimum and maximum, including max="-1"

تغيير النسخ يتطلب ربط dataset مسمىً ضمنيًا وأسماء بيانات XML من ASCII؛ وربط مرجع البيانات الصريح وسياقات الآباء المبهمة يُرفضان قبل نشر المعاملة

Targets resolve through named template children in the event's enclosing scopes, including dotted paths and this.parent; a manager nested inside a repeated scope uses the event's own data group

presence accepts visible, hidden, and invisible on template fields, draws, subforms, and exclusion groups; hidden content occupies no flow space, while invisible content retains its space and is omitted from widgets and flatten output

With the default literal parser, presence changes apply to the selected template node and therefore all its repeated occurrences; indexed per-instance presence, inactive, arbitrary expressions, variables, conditionals, loops, and other event-script operations require an additional event host

دفعة الحدث تنشر تغييرات البيانات والحسابات والتخطيط والتركيز وحالة التحرير معًا بعد استقرار إعادة التدفق؛ وأي عملية مرفوضة أو ميزانية إدخال أو عمليات أو نسخ أو قيم أو widgets أو تخطيط أو زمن منقضٍ مستنفدة تستعيد المستند وحالة التفاعل السابقة كاملةً

إزالة صف تحفظ التركيز والتعديلات المعلقة لمجموعات البيانات الباقية حتى عند تغير فهارس widgets؛ وإزالة أو إخفاء widget المركز تمسح التركيز وتنشر callback التركيز المقابل بعد النجاح

تنفيذ أحداث JavaScript وFormCalc العام

Set TXFAWidgetRuntimeOptions.ScriptOptions.EnableJavaScript to enable the shipped bounded QuickJS bridge for event execution; JavaScript events then support functions, closures, arrays, conditions, loops and exceptions rather than the default literal grammar

Options := TXFAWidgetRuntimeOptions.Default;
Options.ScriptOptions.EnableJavaScript := True;
Runtime := TXFAWidgetRuntime.Create(XDPBytes, 595, 842, Options);

The event host exposes this, enclosing named fields and subforms, parent, writable rawValue, presence and access, instanceManager.count/min/max, addInstance, removeInstance, insertInstance, moveInstance and setInstances, xfa.resolveNode, xfa.resolveNodes, node-level resolution and xfa.layout.relayout

Node lists support numeric indexing, length and item; repeated field values retain their own dataset targets, and SOM paths accept named children with numeric or wildcard indices for live host nodes

const values = xfa.resolveNodes("main.row[*].amount[*]");
let total = 0;
for (const field of values) total += Number(field.rawValue);
xfa.resolveNode("main.total").rawValue = total;
if (total > 100) this.parent.warning.presence = "visible";

Each repeated subform has its own live object and child fields; index, parent child getters and subsequent SOM queries follow insert, move and remove operations immediately inside the script

addInstance and insertInstance return a live subtree initialized from template defaults, so the script can write its field values before the event publishes; removed handles reject subsequent reads or writes

General script presence and access changes persist in the standard XFA form packet per occurrence, while field values and repeat operations persist in datasets; insert, move and remove keep the corresponding form state aligned with the data groups

With the same opt-in, FormCalc event scripts compile to the bounded engine and support var, if/elseif/else, for with upto or downto, while, foreach, func with implicit results, arithmetic and comparisons, string concatenation, wildcard node aggregation and implicit field-value assignment

The event function library includes Sum, Count, Avg, Min, Max, Round, common math functions, string slicing, case conversion, trimming, replacement, HasValue, Exists, Within, Oneof and Choose; built-in names are case insensitive, At(source, search) follows XFA argument order including empty-search behavior, financial functions follow XFA parameter order, and the date and finance catalogues are described in دوال FormCalc

تغييرات السكربت تسجل داخل المحرك وتفحص وتعاد داخل معاملة بيئة التشغيل؛ والاستثناءات والمقاطعة وUnicode غير الصالح وعمليات المضيف غير الصالحة والميزانيات المستنفدة لا تنشر تغييرات مستند جزئية

General script execution remains off by default, uses no browser or external process, and exposes no filesystem, network or application APIs; the caller may supply JavaScriptEvaluator instead of the bridge

كائنات السكربت الدائمة

JavaScript script objects inside a subform's variables element expose their variables and functions through the script name; lexical variables, object state and nested closures remain alive for the runtime session, with normal lexical shadowing and strict directives preserved

<variables>
  <script name="Helpers" contentType="application/x-javascript"><![CDATA[
    let count = 0;
    const nextPrivate = (() => { let value = 0; return () => ++value; })();
    function next() { return ++count + ":" + nextPrivate(); }
  ]]></script>
</variables>

Event code can call Helpers.next(); repeated subform occurrences own independent script objects, and functions resolve named fields against the current live form context

عقد الحقول الملتقطة والمدراء تتبع هوية البيانات المستقرة عبر النقل ونشر النسخ المنشأة حديثًا؛ والوصول إلى عقدة مزالة يرفض الحدث ويتراجع عن حالة وحدته

General calculate and validate scripts share the session and script objects; JavaScript supports implicit completion values and explicit return, while FormCalc returns its final expression

المعاملات الفاشلة تستعيد الحالة المعجمية والclosure بإعادة تشغيل السجل الافتراضي الملتزم، بالزمن والمدخلات العشوائية المسجلين؛ وتتقاسم إعادة التشغيل والتنفيذ الحالي مهلة المعاملة، وحدود السجل الافتراضية 64 MiB من السكربتات/النتائج و8192 مدخلًا

Script-object state lives in the runtime session and is initialized again after XDP reload; standard document values and form overrides continue to persist through SaveToBytes

Custom JavaScriptEvaluator callbacks retain the existing native calculate/validate envelope; the persistent session is supplied by the shipped engine

هيّئ نقل المضيف الصريح

Set HostTransport and optional OnHostTransactionCompleted in TXFAWidgetRuntimeOptions لتنفيذ dialogs المضيف والطباعة والتنقل والإرسال ونقل البيانات عبر callbacks التطبيق

نقل مضيف XFA الصريح supplies xfa.host.messageBox, response, beep, print, gotoURL, submitForm, importData, exportData and FormCalc Get, Post and Put; the application returns typed results and controls external effects

إعادة المحاولات وإعادة تشغيل الجلسة تستخدمان الاستجابات المسجلة فتاجرِ callbacks مرة واحدة لكل طلب مرسل؛ وإتمام الفشل يتيح للتطبيق إهمال تأثيرات مجهزة أو تعويض عمليات قابلة للعكس

Positive HostTransportLimits bound request count, argument count and aggregate request/response bytes across the enclosing runtime transaction

تنفيذ locale والصور

أحداث FormCalc العامة وسكربتات calculate وvalidate تدعم دوال locale والصور، بما يشمل Format وParse وتحويلات التاريخ/الوقت المحلية والوحدات والترميز وUUIDs وكلمات الأعداد الإنجليزية

Eval الديناميكي في FormCalc تنفذ حسابات مزودة ديناميكيًا بمتغيرات ودوال معزولة ووصول حقول نسبيًا وتجميعًا أصليًا واستجابات مسجلة وتراجعًا بمعاملات

مراجع FormCalc الصريحة تدعم إسنادًا كتابيًا مباشرًا وإعادة ربط وفصل null ووسائط دوال ومقبضات مستقرة تحتفظ بها كائنات السكربت عبر حركة النسخ المتكررة

مسارات SOM الحية تدعم فهارس تكرار مستنتجةً ومطلقةً ونسبيةً ومحددات أصناف وسلالة وحاويات شفافة ومسندات مرشحين وإسنادًا مفهرسًا مباشرًا في FormCalc

كائن نتيجة Data DOM الأصلي يُتيح datasets عبر $data و$record ويزامن قراءات وكتابات النماذج المربوطة فورًا ويعكس النسخ المتكررة ويحفظ مراجع البيانات المحتفظ بها عبر نشر هوية أصلي

كائن نتيجة DOM الخصائص الأصلي يُتيح أبناء القيمة والخط وUI وخصائص أخرى مصرحًا بهم ويزامن قيم الحقول الموسومة ويديم سمات لكل نسخة يستخدمها قياس الخطوط وتسويط التسطيح المدعوم

العقدة المنفذة ترث أقرب سمة locale لها؛ ومدخلات localeSet للمستند تتجاوز الرموز والأنماط النظامية، بينما أسماء locale المحسوبة تحل عبر طلبات داخلية محدودةً بحدود وتحفظ في سجل الجلسة

Num2Date بلا صورة تستخدم الآن نمط التاريخ الافتراضي المحيط؛ وزوّد YYYY-MM-DD صراحةً عند اشتراط إخراج ISO

نموذج المضيف ذو الحالة

نموذج مضيف XFA يزود بيانات وصف التطبيق وعدد الصفحات الفعلي والتنقل بين الصفحات وعنوان Unicode وأعلام الحساب/التحقق وإعادة ضبط محدودة النطاق وتركيز الحقول بدورة حياة enter/exit بمعاملات

TXFAWidgetRuntimeOptions.HostModel تهيئ حالة التطبيق الأولية؛ وTXFAWidgetRuntime.HostModel تعيد الحالة الحالية، والأحداث الفاشلة تستعيدها مع لقطات المستند والتفاعل

نقل تركيز بلا سكربت enter/exit أو تعديل معلق أو دورة حياة مهيأة يغيّر التركيز دون بدء حساب سكربت أو معالجة مهلة؛ وتركيز مبرمجًا والتزامات التعديل المعلقة ما تزالان يستخدمان ميزانيات بمعاملات وتحققًا وإعادة حساب

بنود الصور المتقدمة تنفذ عبر معاملات بيئة التشغيل نفسها وسجل إعادة محاولة locale ودورة حياة الحساب، بتحليل مركب محدودًا بحدود

هيّئ الدورة الحياة واحفظها

استدعِ InitializeForm بعد تهيئة بيئة التشغيل وcallbacks لتنفيذ أحداث initialize بترتيب القالب ثم calculate وvalidate وأحداث form-ready وأحداث layout-ready؛ والاستدعاء مطابق الأثر بعد النجاح

النسخ المنشأة بالتهيئة أو أحداث ready تتلقى أحداث initialize الخاصة بها قبل معالجات ready لها؛ وتنفيذ layout-ready يكرر فقط عند تغير التخطيط، داخل ميزانيتي إعادة التدفق والمعاملة

بعد التهيئة، يهيئ إرسال الحدث الناجح والتزام التحرير النسخ المنشأة حديثًا وينفذان calculate وvalidate وlayout-ready؛ والتكرارات القائمة تحفظ حالة تهيئتها عبر النقل وتراجع المعاملة

فشول دورة الحياة تتراجع عن بايتات المستند وتفاعل widgets وسجلات التهيئة معًا، وcallbacks تنشر فقط بعد نجاح المعاملة المحيطة

احفظ النموذج المحدَّث

SaveToBytes returns the runtime's complete updated XDP, including modified datasets and standard per-instance form state; literal-parser presence changes remain template attributes; use these bytes with SetXFADocument when writing a PDF or with HPDFXFAFlatten for the updated flatten output

مصنع المستندات المحملة ينشئ بيئة تشغيل مستقلة، فأحداث بيئة التشغيل لا تغيّر تلقائيًا رسم كائنات PDF المصدر

ملف عرض النسخ الاختياري

عرض نسخ XFA الديناميكي يضيف روابط متكررة صريحةً ومعرفات مستقرة لكل نسخة وحضورًا ووصولًا مفهرسين وأحداثًا شرطية محدودةً بحدود ورسم canvas للمضيف وإتاحة عبر مساعد مستقل؛ وتبقى بيئة التشغيل الافتراضية وقواعد أحداثها المقيّدة متوافقة

UpdateDocument provides transactional document actions; optional runtime property, binding-scope, identity, resolution-started, and document-validation callbacks support the helper while nil defaults preserve existing callers

واجهات الأحداث والنماذج الأدنى مستوى

HPDFXFACompileFormCalcEvent تجمع صياغة الحدث؛ HPDFXFAExecuteJavaScriptEvent تنفذ السياق الافتراضي الموصوف من TXFAEventBinding و TXFAEventBindings

TXFAJavaScriptSession تزود تنفيذًا دائمًا ونقاط فحص محدودةً بحدود للمستدعين الأدنى مستوى

قيم TXFAEventAction المُعادة تستخدم TXFAEventActionKind؛ وإعادة التشغيل بمعاملات تزودها بيئة التشغيل

HPDFXFAResolveFormInstanceNode و HPDFXFAResolveFormInstanceProperty تزودان بحثًا محدودًا بحدود لحزمة النموذج القياسية

الحدود الحالية

بيئة التشغيل كائن مضيف أحادي الخيط؛ وGUI والرسم يبقيان مسؤولية المضيف أو مساعد العرض الاختياري

حالة المضيف المدعومة وDOM النموذج الحية ودورة الحياة لا تغطي بعد كل خاصية مضيف Acrobat أو صور الأرقام لعصور بديلة ومحليةً أو استعلامات إعادة تدفق ديناميكية متزامنة أو كل معامِل SOM

راجع FormCalc وJavaScript في XFA محدودين بحدود، DOM حزمة XFA، و المعالجة التفاعلية للمستندات