Interactive Dynamic XFA Widget Runtime

TXFAWidgetRuntime leverer en værts-neutral interaktionsmodel for dynamiske XFA-formularer uden at konvertere dem til AcroForm-felter eller fladgøre deres indhold

Runtime'et udsætter deterministiske widget-grænser og -tilstand, så et desktop-, service- eller brugerdefineret renderer kan levere sit eget input, maling, tilgængelighed og event-loop

Opret et runtime

Opret runtime'et direkte fra XDP-bytes, eller kald THotPDF.CreateLoadedXFAWidgetRuntime efter at have indlæst en PDF, hvis AcroForm indeholder en single-stream- eller packet-array-/XFA-indgang

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;

Den indlæste-dokument-fabrik er skrivebeskyttet med hensyn til PDF-objektgrafen og eksisterende XFAFlattenWarnings; at gemme dokumentet bevarer dets oprindelige /XFA- og /NeedsRendering-indgange

Interaktionsmodel

Interaktive commits synkroniserer eksisterende native scalar-værdier i skjulte og usynlige aliasser, inklusive faktiske gentagne data-scopes og byte-eksakt rollback

Atomisk validering og beregning

Et commit opløser eksplicitte SOM-bindinger og den aktuelle gentagne-række-datakontekst, før validate- og calculate-scripts kører

Den redigerede værdi, beregnede værdier, datanoder, widgetmodellen, fokus- og redigeringstilstand, advarsler og pass-tællere publiceres sammen først, efter at validering og layout stabiliserer sig

Afviste scripts, udtømte budgetter, ugyldige UTF-16-udvalgsgrænser og layout- eller værtsmålings-exceptions gendanner den komplette tidligere tilstand og sætter LastDiagnostic

Budgetter

TXFAWidgetRuntimeOptions begrænser widget-antal, længde af redigeret værdi, beregnings-pass, reflow-pass, layout-operationer, script-operationer, forløbet script-tid og andre FormCalc- eller JavaScript-ressourcer

Widget-taket gælder, mens layout-elementer og pagineringsfragmenter tilføjes, mens indlæst XFA-dekomprimering og pakkeassemblering stopper ved XFA-DOM-inputgrænsen før parsing

MaxLayoutOperations har 200000 som standard og afgrænser både dokumentgennemløb og layoutarbejde; layoutdybden er begrænset til 128, dybden af event-mål og instansinitialisering til 64, og rekursiv event-dispatch afvises

Default literal dynamiske events

DispatchEvent accepterer semikolonseparerede literale operationer i matchende felt-event-scripts med FormCalc- eller JavaScript-indholdstyper; disse operationer parses direkte og kræver ingen JavaScript-DLL

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

addInstance tilføjer én instans og accepterer true, false, 1 eller 0 som sit merge-argument; et udeladt argument bruger true, og shorthanden _row.addInstance(1) accepteres også

Den understøttede model binder hver eksisterende datagruppe med samme navn, så en ny instans får en ny datagruppe initialiseret fra skabelonstandarderne uanset merge-argument; instansoprettelse kloner ikke den forrige rækkes indtastede værdier

removeInstance bruger et nulbaseret heltalsindeks blandt den valgte subforms datagrupper med samme navn; subformen skal have et occur-element med et repeterbart maksimum, og begge operationer håndhæver dets minimum og maksimum, inklusive max="-1"

Instansmutation kræver implicit navngiven dataset-binding og ASCII-XML-datanavne; eksplicit datareference-binding og tvetydige forældrekontekster afvises, før transaktionen publiceres

Mål opløses gennem navngivne skabelonbørn i eventets omsluttende scopes, inklusive punkterede stier og this.parent; en manager indlejret i et gentaget scope bruger eventets egen datagruppe

presence accepterer visible, hidden og invisible på skabelonfelter, draws, subforms og exclusion-grupper; skjult indhold optager ingen flowplads, mens usynligt indhold bevarer sin plads og udelades fra widgets og flatten-output

Med standard literal-parseren gælder presence-ændringer den valgte skabelonnode og dermed alle dens gentagne forekomster; indekseret per-instans-presence, inactive, vilkårlige udtryk, variabler, betingelser, løkker og andre event-script-operationer kræver en ekstra event-vært

En event-batch publicerer dataændringer, beregninger, layout, fokus og redigeringstilstand sammen, efter reflowet stabiliserer sig; enhver afvist operation eller opbrugt input-, operations-, instans-, værdi-, widget-, layout- eller forløbet-tids-budget gendanner den komplette tidligere dokument- og interaktionstilstand

Fjernelse af en række bevarer fokus og ventende redigeringer for overlevende datagrupper, selv når deres widget-indekser ændres; fjernelse eller skjulning af den fokuserede widget rydder fokus og publicerer det tilsvarende fokus-callback efter succes

Generel JavaScript- og FormCalc-event-udførelse

Sæt TXFAWidgetRuntimeOptions.ScriptOptions.EnableJavaScript for at aktivere den vedlagte afgrænsede QuickJS-bro til event-udførelse; JavaScript-events understøtter derefter funktioner, closures, arrays, betingelser, løkker og exceptions i stedet for den standard literal-grammatik

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

Event-værten eksponerer this, omsluttende navngivne felter og subforms, parent, skrivbar rawValue, presence og access, instanceManager.count/min/max, addInstance, removeInstance, insertInstance, moveInstance og setInstances, xfa.resolveNode, xfa.resolveNodes, node-niveau-opløsning og xfa.layout.relayout

Nodelister understøtter numerisk indeksering, length og item; gentagne feltværdier beholder deres egne dataset-mål, og SOM-stier accepterer navngivne børn med numeriske eller wildcard-indekser for levende værtsnoder

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";

Hver gentagen subform har sit eget levende objekt og børnefelter; index, forælder-børn-getters og efterfølgende SOM-forespørgsler følger insert-, move- og remove-operationer øjeblikkeligt inde i scriptet

addInstance og insertInstance returnerer et levende subtræ initialiseret fra skabelonstandarderne, så scriptet kan skrive sine feltværdier, før eventet publicerer; fjernede handles afviser efterfølgende læsninger eller skrivninger

Generelle script presence- og access-ændringer persistere i standard XFA form-packet pr. forekomst, mens feltværdier og repeat-operationer persistere i datasets; insert, move og remove holder den tilsvarende form-tilstand afstemt med datagrupperne

Med samme opt-in kompilerer FormCalc-event-scripts til den afgrænsede engine og understøtter var, if/elseif/else, for med upto eller downto, while, foreach, func med implicitte resultater, aritmetik og sammenligninger, strengkonkatenation, wildcard-node-aggregering og implicit feltværdi-tildeling

Event-funktionsbiblioteket inkluderer Sum, Count, Avg, Min, Max, Round, almindelige matematikfunktioner, strengudskæring, case-konvertering, trimming, erstatning, HasValue, Exists, Within, Oneof og Choose; indbyggede navne er case-insensitive, At(source, search) følger XFA-argumentrækkefølgen inklusive tom-søgnings-opførsel, finansielle funktioner følger XFA-parameterrækkefølgen, og dato- og finanskatalogerne er beskrevet i FormCalc Functions

Script-mutationer optages inde i enginen, valideres og afspilles igen inde i runtime-transaktionen; exceptions, afbrydelse, ugyldig Unicode, ugyldige værtsoperationer og opbrugte budgetter publicerer ingen delvise dokumentændringer

Generel script-udførelse er som standard slået fra, bruger ingen browser eller ekstern proces og eksponerer ingen filsystem-, netværks- eller applikations-API'er; kalderen kan levere JavaScriptEvaluator i stedet for broen

Persistente script-objekter

JavaScript script-objekter inde i en subforms variables-element eksponerer deres variabler og funktioner gennem scriptnavnet; leksikalske variabler, objekttilstand og nestede closures forbliver levende for runtime-sessionen, med normal leksikalsk skygge og strict directives bevaret

<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-kode kan kalde Helpers.next(); gentagne subform-forekomster ejer uafhængige script-objekter, og funktioner opløser navngivne felter mod den aktuelle levende form-kontekst

Fangne feldenoder og managers følger stabil dataidentitet på tværs af flytninger og publicering af nyoprettede instanser; adgang til en fjernet node afviser eventet og ruller dets modultilstand tilbage

Generelle calculate- og validate-scripts deler sessionen og script-objekterne; JavaScript understøtter implicitte completion-værdier og eksplicit return, mens FormCalc returnerer sit sidste udtryk

Fejlede transaktioner gendanner leksikalsk og closure-tilstand ved at afspille den committere virtuelle journal igen, med optaget tid og tilfældige inputs; replay og aktuel udførelse deler transaktionsdeadlinen, og standard journal-grænser er 64 MiB scripts/resultater og 8192 poster

Script-objekttilstand lever i runtime-sessionen og initialiseres igen efter XDP-genindlæsning; standard dokumentværdier og form-overrides persistere fortsat gennem SaveToBytes

Brugerdefinerede JavaScriptEvaluator-callbacks bevarer den eksisterende native calculate/validate-kuvert; den persistente session leveres af den vedlagte engine

Konfigurér eksplicit værtstransport

Sæt HostTransport og valgfri OnHostTransactionCompleted i TXFAWidgetRuntimeOptions for at udføre værtsdialoger, udskrivning, navigation, submission og dataoverførsel gennem applikations-callbacks

Eksplicit XFA Host Transport leverer xfa.host.messageBox, response, beep, print, gotoURL, submitForm, importData, exportData samt FormCalc Get, Post og Put; applikationen returnerer typede resultater og styrer eksterne effekter

Retries og session-replay bruger optagede svar, så callbacks udføres én gang pr. dispatchet forespørgsel; fejlsvar lader applikationen kassere stagede effekter eller kompensere reversible operationer

Positive HostTransportLimits afgrænser forespørgselsantal, argumentantal og aggregerede forespørgsels-/svar-bytes på tværs af den omsluttende runtime-transaktion

Locale- og picture-udførelse

Generelle FormCalc-events, calculate- og validate-scripts understøtter locale- og picture-funktioner, inklusive Format, Parse, lokaliserede dato/tids-konverteringer, enheder, encoding, UUID'er og engelske talord

Dynamisk FormCalc Eval udfører dynamisk leverede beregninger med isolerede variabler og funktioner, relativ feltadgang, native kompilering, optagede svar og transaktionel rollback

Eksplicitte FormCalc-referencer understøtter write-through-tildeling, rebinding, null-detachment, funktionsargumenter og stabile handles fastholdt af script-objekter på tværs af repeated-instance-flytninger

Levende SOM-stier understøtter udledte, absolutte og relative forekomstindekser, klasse- og efterkommer-selektorer, transparente containere, kandidat-prædikater og direkte FormCalc indekseret tildeling

Den native Data DOM eksponerer datasets gennem $data og $record, synkroniserer bundne form-læsninger og -skrivninger øjeblikkeligt, spejler gentagne instanser og bevarer fastholdte datareferencer gennem native identitetspublicering

Den native Property DOM eksponerer deklarerede value-, font-, UI- og andre property-børn, synkroniserer typede feltværdier og persistere per-instance-attributter brugt af fontmåling og understøttet flatten-styling

Den udførende node arver sin nærmeste locale-attribut; dokumentets localeSet-poster overskrider systemsymboler og -mønstre, mens beregnede locale-navne opløses gennem afgrænsede interne forespørgsler og bevares i sessionsjournalen

Num2Date uden picture bruger nu det omgivende default-datamønster; giv YYYY-MM-DD eksplicit, når ISO-output er påkrævet

Stateful værtsmodel

XFA Host Model leverer applikationsmetadata, faktisk sideantal, sidenavigation, Unicode-titel, beregnings-/valideringsflag, scopet reset og feltfokus med transaktionel enter/exit-livscyklus

TXFAWidgetRuntimeOptions.HostModel konfigurerer oprindelig applikationstilstand; TXFAWidgetRuntime.HostModel returnerer aktuel tilstand, og fejlede events gendanner den sammen med dokument- og interaktions-snapshots

Et fokus-skift uden enter/exit-script, ventende redigering eller initialiseret livscyklus ændrer fokus uden at starte script-beregning eller deadline-behandling; scriptet fokus og ventende edit-commits bruger stadig transaktionelle budgetter, validering og genberegning

Avancerede picture clauses udføres gennem de samme runtime-transaktioner, locale-retry-journal og beregningslivscyklus med afgrænset compound-parsing

Initialisér og vedligehold livscyklussen

Kald InitializeForm efter konfiguration af runtime og callbacks for at udføre initialize-events i skabelonrækkefølge, derefter calculate og validate, form-ready-events og layout-ready-events; kaldet er idempotent efter succes

Nye instanser oprettet af initialisering eller ready-events modtager deres egne initialize-events, før deres ready-handlers; layout-ready-udførelse gentages kun, når layoutet ændres, inden for reflow- og transaktionsbudgetterne

Efter initialisering initialiserer vellykket event-dispatch og edit-commit nyoprettede instanser og udfører calculate, validate og layout-ready; eksisterende forekomster bevarer deres initialiseringstilstand på tværs af flytninger og transaktions-rollback

Livscyklusfejl ruller dokumentbytes, widget-interaktion og initialiseringsbogholderi tilbage sammen, og callbacks publicerer først, efter at den omsluttende transaktion lykkes

Gem den opdaterede formular

SaveToBytes returnerer runtime'ets komplette opdaterede XDP, inklusive ændrede datasets og standard per-instance-formtilstand; literal-parser presence-ændringer forbliver skabelonattributter; brug disse bytes med SetXFADocument ved skrivning af en PDF eller med HPDFXFAFlatten til det opdaterede flatten-output

Den indlæste-dokument-fabrik opretter et uafhængigt runtime, så runtime-events ikke automatisk ændrer kilde-PDF'ens objektgraf

Valgfri instanspræsentationsprofil

Dynamic XFA Instance Presentation tilføjer eksplicitte gentagne bindinger, stabile per-instance-ID'er, indekseret presence og adgang, afgrænsede betingede events, host canvas-maling og tilgængelighed gennem en uafhængig hjælper; standard-runtime'et og dets begrænsede event-grammatik forbliver kompatible

UpdateDocument leverer transaktionelle dokumenthandlinger; valgfri runtime property-, binding-scope-, identitets-, resolution-started- og dokumentvaliderings-callbacks understøtter hjælperen, mens nil-defaults bevarer eksisterende kaldere

Lavniveau-event- og formular-API'er

HPDFXFACompileFormCalcEvent kompilerer event-syntaks; HPDFXFAExecuteJavaScriptEvent udfører den virtuelle kontekt beskrevet af TXFAEventBinding og TXFAEventBindings

TXFAJavaScriptSession leverer persistent udførelse og afgrænsede checkpoints til lavniveau-kaldere

Returnerede TXFAEventAction-værdier bruger TXFAEventActionKind; transaktionel replay leveres af runtime'et

HPDFXFAResolveFormInstanceNode og HPDFXFAResolveFormInstanceProperty leverer afgrænset standard form-packet-opslag

Aktuelle grænser

Runtime'et er et enkelt-trådet værtsobjekt; GUI og maling forbliver værtens eller den valgfri præsentationshelpers ansvar

Den understøttede værtstilstand, levende form-DOM og livscyklus dækker endnu ikke alle Acrobat værtsegenskaber, alternate-era- og lokaliserede ciffer-pictures, synkrone dynamiske reflow-forespørgsler eller alle SOM-operatorer

Se Bounded XFA FormCalc and JavaScript, XFA Packet DOM og Interactive Document Processing