Interaktiv dynamisk XFA-widgetkörtid

TXFAWidgetRuntime tillhandahåller en värdneutral interaktionsmodell för dynamiska XFA-formulär utan att konvertera dem till AcroForm-fält eller platta ut deras innehåll

Körtiden exponerar deterministiska widgetgränser och tillstånd så att en skrivbords-, tjänste- eller anpassad renderare kan leverera sin egen inmatning, målning, tillgänglighet och händelseslinga

Skapa en körtid

Skapa körtiden direkt ur XDP-byte eller anropa THotPDF.CreateLoadedXFAWidgetRuntime efter att ha läst in en PDF vars AcroForm innehåller en enströms- eller paketarray-/XFA-post

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 inläst-dokument-fabriken är skrivskyddad med avseende på PDF-objektgrafen och befintliga XFAFlattenWarnings; att spara dokumentet behåller dess ursprungliga /XFA- och /NeedsRendering-poster

Interaktionsmodell

Interaktiva sparanden synkroniserar befintliga nativa skalärvärden i dolda och osynliga alias, inklusive faktiska upprepade datascopes och byteexakt rullering

Atomisk validering och beräkning

Ett sparande löser explicita SOM-bindningar och aktuell upprepad-rad-datakontext innan validate- och calculate-skripten körs

Det redigerade värdet, beräknade värden, datanoder, widgetmodellen, fokus- och redigeringstillstånd, varningar och passräknare publiceras tillsammans först efter att validering och layout stabiliserats

Avvisade skript, uttömda budgetar, ogiltiga UTF-16-valgränser samt layout- eller värdmätningsundantag återställer hela det tidigare tillståndet och sätter LastDiagnostic

Budgetar

TXFAWidgetRuntimeOptions begränsar widgetantal, längd på redigerat värde, beräkningspass, reflow-pass, layoutoperationer, skriptoperationer, förfluten skripttid och andra FormCalc- eller JavaScript-resurser

Widgettaket tillämpas medan layoutobjekt och pagineringsfragment läggs till, medan inläst XFA-dekomprimering och paketsammansättning stannar vid XFA DOM-inkomstgränsen innan tolkning

MaxLayoutOperations har standardvärdet 200000 och avgränsar både dokumentgenomgången och layoutarbetet; layoutdjupet begränsas till 128, djupet för händelsemål och instansinitiering till 64, och rekursiv händelseutsändning avvisas

Standard literala dynamiska händelser

DispatchEvent accepterar semikolonseparerade literala operationer i matchande fälthändelseskript med FormCalc- eller JavaScript-innehållstyp; de här operationerna tolkas direkt och kräver ingen JavaScript-DLL

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

addInstance lägger till en instans och accepterar true, false, 1 eller 0 som sitt merge-argument; ett utelämnat argument använder true, och stenografin _row.addInstance(1) godtas också

Den stödda modellen binder varje befintlig datagrupp med samma namn, så att en ny instans får en ny datagrupp initierad från mallens standardvärden oavsett merge-argument; instansskapandet klonar inte föregående rads inmatade värden

removeInstance använder ett nollbaserat heltalsindex bland den valda delformulärets datagrupper med samma namn; delformuläret måste ha ett occur-element med ett repeterbart maximum, och båda operationerna tvingar fram dess minimum och maximum, inklusive max="-1"

Instansmutation kräver implicit namngiven datauppsättningsbindning och ASCII-namn på XML-data; explicit datareferensbindning och tvetydiga föräldrakontexter avvisas innan transaktionen publiceras

Mål löses genom namngivna mallbarn i händelsens omslutande scope, inklusive punktade sökvägar och this.parent; en manager nästlad inuti ett upprepat scope använder händelsens egen datagrupp

presence accepterar visible, hidden och invisible på mallfält, draw-element, delformulär och exkluderingsgrupper; dolt innehåll upptar inget flödesutrymme, medan osynligt innehåll behåller sitt utrymme och utelämnas från widgetar och flatten-utdata

Med standard literaltolkaren tillämpas närvaroändringar på den valda mallnoden och därmed på alla dess upprepade förekomster; indexerad per-instans-närvaro, inactive, godtyckliga uttryck, variabler, villkor, loopar och andra händelseskriptoperationer kräver en ytterligare händelsevärd

En händelsebatch publicerar dataändringar, beräkningar, layout, fokus och redigeringstillstånd tillsammans efter att reflow stabiliserats; varje avvisad operation eller uttömd budget för indata, operationer, instanser, värden, widgetar, layout eller förfluten tid återställer hela det tidigare dokument- och interaktionstillståndet

Att ta bort en rad bevarar fokus och pågående ändringar för överlevande datagrupper även när deras widgetindex ändras; att ta bort eller dölja den fokuserade widgeten rensar fokus och publicerar motsvarande fokusåteranrop efter lyckat resultat

Generell JavaScript- och FormCalc-händelseexekvering

Sätt TXFAWidgetRuntimeOptions.ScriptOptions.EnableJavaScript för att aktivera den medföljande avgränsade QuickJS-bryggan för händelseexekvering; JavaScript-händelser stödjer då funktioner, closures, arrayer, villkor, loopar och undantag i stället för den literala standardgrammatiken

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

Händelsevärden exponerar this, omslutande namngivna fält och delformulär, parent, skrivbar rawValue, presence och access, instanceManager.count/min/max, addInstance, removeInstance, insertInstance, moveInstance och setInstances, xfa.resolveNode, xfa.resolveNodes, nodnivåupplösning och xfa.layout.relayout

Nodlistor stödjer numerisk indexering, length och item; upprepade fältvärden behåller sina egna datasetmål, och SOM-sökvägar accepterar namngivna barn med numeriska eller joker-index för levande värdnoder

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

Varje upprepat delformulär har sitt eget levande objekt och barnfält; index, förälders barnåtkomster och efterföljande SOM-frågor följer insert-, move- och remove-operationer direkt inuti skriptet

addInstance och insertInstance returnerar ett levande underträd initierat ur mallstandarder, så att skriptet kan skriva sina fältvärden innan händelsen publiceras; borttagna handles avvisar efterföljande läsningar eller skrivningar

Generella skriptnärvaro- och åtkomständringar består i standard-XFA-form-paketet per förekomst, medan fältvärden och upprepningsoperationer består i datasets; insert, move och remove håller motsvarande formulärtillstånd synkat med datagrupperna

Med samma tillval kompilerar FormCalc-händelseskript till den avgränsade motorn och stödjer var, if/elseif/else, for med upto eller downto, while, foreach, func med implicita resultat, aritmetik och jämförelser, strängkonkatenering, jokernodaggregering och implicit fältvärdetilldelning

Händelsefunktionsbiblioteket inkluderar Sum, Count, Avg, Min, Max, Round, vanliga matematiska funktioner, strängskivning, skiftlägeskonvertering, trimning, ersättning, HasValue, Exists, Within, Oneof och Choose; inbyggda namn är skiftlägesokänsliga, At(source, search) följer XFA:s argumentordning inklusive beteende vid tom sökning, finansfunktioner följer XFA:s parameterordning, och datum- och finanskatalogerna beskrivs i FormCalc-funktioner

Skriptmutationer registreras inuti motorn, valideras och spelas upp inuti körtidstransaktionen; undantag, avbrott, ogiltig Unicode, ogiltiga värdoperationer och uttömda budgetar publicerar inga partiella dokumentändringar

Generell skriptexekvering förblir avstängd som standard, använder ingen webbläsare eller extern process och exponerar inga filsystems-, nätverks- eller applikations-API:er; anroparen kan i stället tillhandahålla JavaScriptEvaluator

Bestående skriptobjekt

JavaScript-script-objekt inuti ett delformulärs variables-element exponerar sina variabler och funktioner genom skriptnamnet; lexikala variabler, objekt tillstånd och kapslade closures förblir vid liv för körtidssessionen, med normal lexikalisk skuggning och strikta direktiv bevarade

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

Händelsekod kan anropa Helpers.next(); upprepade delformulärsförekomster äger oberoende skriptobjekt, och funktioner löser namngivna fält mot aktuell levande formulärkontext

Fångade fältnoder och hanterare följer stabil dataidentitet över flyttar och publicering av nyskapade instanser; åtkomst till en borttagen nod avvisar händelsen och rullar tillbaka dess modultillstånd

Generella calculate- och validate-skript delar sessionen och skriptobjekten; JavaScript stödjer implicita slutförandevärden och explicit return, medan FormCalc returnerar sitt slutliga uttryck

Misslyckade transaktioner återställer lexikalt och closure-tillstånd genom att spela upp den sparade virtuella journalen, med registrerad tid och slumpindata; uppspelning och aktuell exekvering delar transaktionens tidsgräns, och journalens standardgränser är 64 MiB skript/resultat och 8192 poster

Skriptobjekt tillstånd lever i körtidssessionen och initieras på nytt efter XDP-omläsning; standarddokumentvärden och formuläröverskrivningar fortsätter att bestå genom SaveToBytes

Anpassade JavaScriptEvaluator-återanrop behåller det befintliga nativa calculate/validate-kuvertet; den bestående sessionen tillhandahålls av den medföljande motorn

Konfigurera explicit värdtransport

Sätt HostTransport och valfri OnHostTransactionCompleted i TXFAWidgetRuntimeOptions för att exekvera värddialoger, utskrift, navigering, sändning och dataöverföring genom applikationsåteranrop

Explicit XFA-värdtransport tillhandahåller xfa.host.messageBox, response, beep, print, gotoURL, submitForm, importData, exportData samt FormCalc Get, Post och Put; applikationen returnerar typade resultat och kontrollerar externa effekter

Nyförsök och sessionsuppspelning använder registrerade svar, så återanrop exekveras en gång per utskickad förfrågan; misslyckat slutförande låter applikationen kassera städade effekter eller kompensera reversibla operationer

Positiva HostTransportLimits begränsar förfrågningsantal, argumentantal och samlade förfrågnings-/svarsbyte över den omslutande körtidstransaktionen

Locale- och picture-exekvering

Generella FormCalc-händelser samt calculate- och validate-skript stödjer locale- och picture-funktioner, inklusive Format, Parse, lokaliserade datum/tid-konverteringar, enheter, kodning, UUID:er och engelska talord

Dynamisk FormCalc Eval exekverar dynamiskt tillhandahållna beräkningar med isolerade variabler och funktioner, relativ fältåtkomst, nativ kompilering, registrerade svar och transaktionell rullering

Explicita FormCalc-referenser stödjer skrivigenom-tilldelning, ombindning, null-frikoppling, funktionsargument och stabila handles som skriptobjekt behåller över upprepningsinstansflytt

Levande SOM-sökvägar stödjer härledda, absoluta och relativa förekomstindex, klass- och ättlingselektorer, transparenta behållare, kandidatpredikat och direkt FormCalc-indexerad tilldelning

Det nativa Data DOM exponerar datasets genom $data och $record, synkroniserar bundna formulärläsningar och skrivningar omedelbart, speglar upprepade instanser och bevarar behållna datareferenser genom nativ identitetspublicering

Det nativa Property DOM exponerar deklarerade value-, font-, UI- och andra egenskapsbarn, synkroniserar typade fältvärden och lagrar per-instans attribut som används av typsnittsmätning och stödd flatten-styling

Den exekverande noden ärver sitt närmaste locale-attribut; dokumentets localeSet-poster åsidosätter systemsymboler och mönster, medan beräknade locale-namn löses genom avgränsade interna förfrågningar och bevaras i sessionsjournalen

Num2Date utan picture använder nu det omgivande standarddatummönstret; ange YYYY-MM-DD explicit när ISO-utdata krävs

Tillståndsbärande värdmodell

XFA-värdmodellen tillhandahåller applikationsmetadata, faktiskt sidantal, sidnavigering, Unicode-titel, beräknings-/valideringsflaggor, scopad återställning och fältfokus med transaktionell enter/exit-livscykel

TXFAWidgetRuntimeOptions.HostModel konfigurerar initialt applikationstillstånd; TXFAWidgetRuntime.HostModel returnerar aktuellt tillstånd, och misslyckade händelser återställer det tillsammans med dokument- och interaktionsögonblicksbilder

En fokusflytt utan enter/exit-skript, väntande redigering eller initierad livscykel ändrar fokus utan att starta skriptberäkning eller tidsgränsbearbetning; skriptstyrt fokus och sparande av väntande redigeringar använder fortfarande transaktionsbudgetar, validering och omberäkning

Avancerade picture-klausuler exekveras genom samma körtidstransaktioner, locale-försöksjournal och beräkningslivscykel, med avgränsad sammansatt tolkning

Initiera och underhåll livscykeln

Anropa InitializeForm efter att körtiden och återanropen konfigurerats för att exekvera initialize-händelser i mallordning, därefter calculate och validate, form-ready-händelser och layout-ready-händelser; anropet är idempotent efter framgång

Nya instanser som skapas av initiering eller ready-händelser får sina egna initialize-händelser före sina ready-hanterare; layout-ready-exekvering upprepas endast när layouten ändras, inom reflow- och transaktionsbudgetarna

Efter initieringen initierar lyckad händelseutsändning och redigeringssparande nyskapade instanser och exekverar calculate, validate och layout-ready; befintliga förekomster behåller sitt initieringstillstånd över flyttar och transaktionsrullering

Livscykelfel rullar tillbaka dokumentbyte, widgetinteraktion och initieringsbokföring tillsammans, och återanrop publicerar först efter att den omslutande transaktionen lyckats

Spara det uppdaterade formuläret

SaveToBytes returnerar körtidens completa uppdaterade XDP, inklusive ändrade datasets och standard per-instans formulärtillstånd; literaltolkarens presence-ändringar förblir mallattribut; använd de bytena med SetXFADocument när en PDF skrivs eller med HPDFXFAFlatten för uppdaterad flatten-utdata

Den inläst-dokument-fabriken skapar en oberoende körtid, så körtidens händelser ändrar inte automatiskt käll-PDF:ens objektgraf

Valfri instanspresentationsprofil

Dynamisk XFA-instanspresentation lägger till explicita upprepade bindningar, stabila per-instans-ID:n, indexerad närvaro och åtkomst, avgränsade villkorliga händelser, värdscanvasmålning och tillgänglighet genom en oberoende hjälpare; standardkörtiden och dess begränsade händelsegrammatik förblir kompatibla

UpdateDocument tillhandahåller transaktionella dokumentåtgärder; valfria körtidsegenskaps-, bindningsscope-, identitets-, upplösningsstart- och dokumentvalideringsåteranrop stödjer hjälparen medan nil-standarder bevarar befintliga anropare

Lägre-nivå-händelse- och formulär-API:er

HPDFXFACompileFormCalcEvent kompilerar händelsesyntax; HPDFXFAExecuteJavaScriptEvent exekverar den virtuella kontext som TXFAEventBinding och TXFAEventBindings beskriver

TXFAJavaScriptSession tillhandahåller bestående exekvering och avgränsade kontrollpunkter för lägre-nivå-anropare

Returnerade TXFAEventAction-värden använder TXFAEventActionKind; transaktionell uppspelning tillhandahålls av körtiden

HPDFXFAResolveFormInstanceNode och HPDFXFAResolveFormInstanceProperty tillhandahåller avgränsad standard formulärpacket-uppslagning

Aktuella gränser

Körtiden är ett enkeltrådat värdobjekt; GUI och målning förblir värden eller den valfria presentationshjälparens ansvar

Det stödda värdtillståndet, den levande formulär-DOM:n och livscykeln täcker ännu inte varje Acrobat-värdegenskap, alternativ-era- och lokaliserade siffer-pictures, synkrona dynamiska reflow-frågor eller varje SOM-operator

Se Avgränsad XFA FormCalc och JavaScript, XFA-paket-DOM och Interaktiv dokumentberedning