Etkileşimli Dinamik XFA Widget Runtime

TXFAWidgetRuntime, dinamik XFA formları için onları AcroForm field'larına dönüştürmeden veya içeriklerini flattening etmeden, host'tan bağımsız bir etkileşim modeli sunar

Runtime, deterministik widget sınırlarını ve durumunu ortaya çıkarır; böylece bir masaüstü uygulaması, servis veya özel renderer kendi input, boyama, erişilebilirlik ve event loop'unu sağlayabilir

Runtime oluşturma

Runtime'ı doğrudan XDP byte'larından oluşturun ya da AcroForm'unda tek stream'li veya packet array'li bir /XFA girdisi bulunan bir PDF yükledikten sonra THotPDF.CreateLoadedXFAWidgetRuntime çağırın

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;

Yüklenen belge factory'si, PDF object graph'ı ve mevcut XFAFlattenWarnings açısından salt okunurdur; belgeyi kaydetmek özgün /XFA ve /NeedsRendering girdilerini korur

Etkileşim modeli

Etkileşimli commit'ler, hidden ve invisible alias'larda mevcut native scalar value'larını eşzamanlar — gerçek tekrar-data scope'larını ve byte-kesin rollback'i dâhil

Atomik doğrulama ve hesaplama

Bir commit, validate ve calculate script'lerini çalıştırmadan önce açık SOM binding'lerini ve geçerli tekrarlanan satır veri bağlamını çözümler

Düzenlenen değer, hesaplanan değerler, veri düğümleri, widget modeli, focus ve edit durumu, uyarılar ve pass sayaçları, doğrulama ile layout stabil hale geldikten sonra birlikte yayımlanır

Reddedilen script'ler, tükenen bütçeler, geçersiz UTF-16 selection sınırları ve layout ya da host ölçüm istisnaları, önceki durumu eksiksiz geri yükler ve LastDiagnostic değerini ayarlar

Bütçeler

TXFAWidgetRuntimeOptions, widget sayısını, düzenlenen değer uzunluğunu, hesaplama turlarını, reflow turlarını, layout işlemlerini, script işlemlerini, geçen script süresini ve diğer FormCalc veya JavaScript kaynaklarını sınırlar

Widget üst sınırı, layout öğeleri ve sayfalandırma parçaları eklenirken uygulanır; yüklü XFA decompression'ı ve packet birleştirme ise parsing'ten önce XFA DOM giriş sınırında durur

MaxLayoutOperations varsayılan olarak 200000'dir ve hem belge gezinmesini hem de layout işini sınırlar; layout derinliği 128 ile, event hedefi ve instance başlatma derinliği 64 ile sınırlıdır ve özyinelemeli event dispatch reddedilir

Kısıtlı dinamik event'ler

DispatchEvent, FormCalc veya JavaScript içerik türüne sahip eşleşen field event script'lerinde noktalı virgülle ayrılmış literal işlemleri kabul eder; bu işlemler doğrudan parse edilir ve bir JavaScript DLL'i gerektirmez

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

addInstance bir instance ekler ve merge argümanı olarak true, false, 1 veya 0 kabul eder; atlanan argüman true kullanır, _row.addInstance(1) kısaltması da kabul edilir

Desteklenen model, mevcut her aynı adlı veri grubunu bağlar; böylece yeni bir instance, hangi merge argümanı kullanılırsa kullanılsın template varsayılanlarından başlatılan yeni bir veri grubu alır. Instance oluşturma, önceki satırın girilmiş değerlerini klonlamaz

removeInstance, seçilen subform'un aynı adlı veri grupları arasında sıfır tabanlı bir tamsayı indeks kullanır; subform tekrarlanabilir bir üst sınıra sahip occur elementine sahip olmalıdır ve her iki işlem de max="-1" dahil minimum ve maksimumu uygular

Instance değişikliği örtük adlandırılmış dataset binding'i ve ASCII XML veri adlarını gerektirir; açık data-reference binding'i ve belirsiz parent bağlamları transaction yayımlanmadan önce reddedilir

Hedefler, event'i saran kapsamlardaki adlandırılmış template çocukları üzerinden çözümlenir; noktalı yollar ve this.parent dahildir. Tekrarlanan bir kapsam içinde iç içe bir manager, event'in kendi veri grubunu kullanır

presence, template field, draw, subform ve exclusion group'larında visible, hidden ve invisible değerlerini kabul eder; hidden içerik akış alanı kaplamaz, invisible içerik ise alanını korur ve widget'lardan ve flatten çıktısından çıkarılır

Presence değişiklikleri seçilen template node'a ve dolayısıyla onun tekrarlanan tüm oluşumlarına uygulanır; indekslenmiş instance başına presence, inactive, rastgele ifadeler, değişkenler, koşullar, döngüler ve diğer event-script işlemleri reddedilir

Bir event batch'i, veri değişikliklerini, hesaplamaları, layout'u, focus'u ve düzenleme durumunu reflow stabil hale geldikten sonra birlikte yayımlar; reddedilen herhangi bir işlem ya da tükenen input, operation, instance, value, widget, layout veya geçen süre bütçesi, önceki belge ve etkileşim durumunu eksiksiz geri yükler

Satır kaldırmak, widget indeksleri değişse bile hayatta kalan veri grupları için focus'u ve bekleyen düzenlemeleri korur; focus'lu widget'ı kaldırmak veya gizlemek focus'u temizler ve başarıdan sonra ilgili focus callback'ini yayımlar

Genel JavaScript ve FormCalc event yürütmesi

Event yürütmesi için shipped sınırlı QuickJS köprüsünü etkinleştirmek için TXFAWidgetRuntimeOptions.ScriptOptions.EnableJavaScript'i ayarlayın; JavaScript event'leri, default literal grameri yerine function'ları, closure'ları, array'leri, koşulları, döngü ve exception'ları destekler

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

Event host, this'i, kapsayan adlandırılmış field ve subform'ları, parent'ı, yazılabilir rawValue'yu, presence ve access'i, instanceManager.count/min/max'ı, addInstance'i, removeInstance'i, insertInstance'ı, moveInstance'ı ve setInstances'i, xfa.resolveNode'u, xfa.resolveNodes'u, node-düzeyi resolution'ı ve xfa.layout.relayout'u açığa çıkarır

Node listeleri sayısal indeksleme, length ve item destekler; tekrar-field value'ları kendi dataset hedeflerini tutar ve SOM path'leri, canlı host node'ları için sayısal veya wildcard indeksli adlandırılmış children kabul eder

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

Her tekrar-subform kendi canlı object'ine ve child field'larına sahiptir; index, parent child getter'ları ve sonraki SOM sorguları, script içinde insert, move ve remove operation'larını anında izler

addInstance ve insertInstance, template default'larından başlatılmış canlı bir subtree döndürür — böylece script, event yayımlanmadan önce field value'larını yazabilir; kaldırılmış handle'lar sonraki okuma/yazmaları reddeder

Genel script presence ve access değişiklikleri, standart XFA form packet'inde occurrence başına kalıcılıaşır; field value'ları ve tekrar operation'ları ise datasets'te kalıcılaşır; insert, move ve remove, karşılık gelen form state'ini data gruplarıyla hizalı tutar

Aynı opt-in ile FormCalc event script'leri sınırlı engine'e derlenir ve var'ı, if/elseif/else'i, upto veya downto'lu for'u, while'ı, foreach'i, örtük sonuçlı func'ı, aritmetik ve karşılaştırmaları, string birleştirmeyi, wildcard node agregasyonunu ve örtük field-value atamasını destekler

Event function kütüphanesi Sum'u, Count'u, Avg'yi, Min'i, Max'ı, Round'u, yaygın matematik function'larını, string dilimleme, büyük-küçük-harf dönüşümü, kırpma ve replacement'ı, HasValue'yı, Exists'i, Within'i, Oneof'u ve Choose'u içerir; built-in adlar büyük-küçük-harf duyumsuzdur, At(source, search) boş-arama davranışı dâhil XFA argüman sırasını izler, finans fonksiyonları XFA parametre sırasını izler ve date ile finance catalogue'ları FormCalc Functions içinde anlatılır

Script mutation'ları engine içinde kayd edilir, runtime transaction'ı içinde doğrulanır ve replay edilir; exception'lar, kesinti, geçersiz Unicode, geçersiz host operation'ları ve tükenmiş bütçeler kısmi belge değişikliği yayımlamaz

Genel script yürütmesi default olarak kapalı kalır, browser veya harici process kullanmaz ve dosya-sistemi, network veya uygulama API'si açığa çıkarmaz; çağıran, köprü yerine JavaScriptEvaluator sağlayabilir

Kalıcı script object'leri

Subform'un variables elementi içindeki JavaScript script object'leri, variable ve function'larını script adı üzerinden açığa çıkarır; lexical variable'lar, object state'i ve iç-ice closure'lar runtime session'ı boyunca canlı kalır — normal lexical shadowing ve strict direktifler korunarak

<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 kodu Helpers.next() çağırabilir; tekrar-subform occurrence'ları bağımsız script object'ler sahiplenir ve function'lar, adını geçtiği alanları mevcut canlı form context'ine karşı çözer

Yakalanan field node'ları ve manager'lar, taşımalar boyunca ve yeni oluşturulan instance'ların yayımında kararlı data identity'yi izler; kaldırılmış bir node'a erişmek event'i reddeder ve module state'ini geri alır

Genel calculate ve validate script'leri session'ı ve script object'leri paylaşır; JavaScript örtük tamamlama value'larını ve açık return'i desteklerken, FormCalc nihai ifadesini döndürür

Başarısız transaction'lar, lexical ve closure state'ini — kayıtlı zaman ve rastgele girdilerle commit edilmiş sanal journal replay'iyle — geri yükler; replay ve mevcut yürütme transaction son tçarihini paylaşır ve default journal limitleri 64 MiB script/result ve 8192 entry'dir

Script-object state, runtime session'ında yaşar ve XDP reload'ından sonra yeniden başlatılır; standart belge value'ları ve form override'ları SaveToBytes üzerinden kalıcı olmaya devam eder

Özel JavaScriptEvaluator callback'leri, mevcut native calculate/validate zarfını korur; kalıcı session shipped engine tarafından sağlanır

Açık host transport yapılandırma

Host dialog'larını, printing'i, navigation'ı, göndermeyi ve data transferini uygulama callback'leri üzerinden yürütmek için TXFAWidgetRuntimeOptions içinde HostTransport'u ve opsiyonel OnHostTransactionCompleted'i ayarlayın

Açık XFA Host Transport, xfa.host.messageBox'u, response'u, beep'i, print'i, gotoURL'yi, submitForm'u, importData'yı, exportData'yı ve FormCalc Get, Post ve Put'u sağlar; uygulama, yazılan sonuçlar döndürür ve harici effect'leri kontrol eder

Retry'ler ve session replay kayıtlı response'ları kullanır — böylece callback'ler dispatch edilmiş istek başına bir kez yürütüllür; başarısızlık tamamlaması, uygulamanın staged effect'leri atmasına veya geri-çevrilebilir operation'ları kompanse etmesine izin verir

Pozitif HostTransportLimits, istek sayısını, argüman sayısını ve toplam istek/response baytlarını kapsayan runtime transaction boyunca sınırlar

Locale ve picture yürütmesi

Genel FormCalc event'leri, calculate ve validate script'leri locale ve picture fonksiyonlarını destekler — Format, Parse, yerelleştirilmiş date/time dönüşümleri, unit'ler, encoding, UUID'ler ve İngilizce sayı kelimeleri dâhil

Dinamik FormCalc Eval, izole variable'ları ve function'ları, göreli field erişimi, native compilation, kayıtlı response'ları ve transactional rollback'iyle dinamik sağlanan hesaplamalar yürütür

Açık FormCalc referansları, write-through atamayı, rebinding'i, null detachment'ı, function argümanlarını ve tekrar-instance hareketi boyunca script object'lerince tutulan kararlı handle'ları destekler

Canlı SOM path'leri, çıkarılmış, mutlak ve göreli occurrence indekslerini, class ve descendant selector'ları, saydam container'ları, aday predicate'leri ve doğrudan FormCalc indeksli atamayı destekler

Native Data DOM, dataset'leri $data ve $record üzerinden açığa çıkarır, bağlı form okuma ve yazmalarını anında eşzamanlar, tekrar instance'ları aynalar ve native identity yayımıyla tutulan data referanslarını korur

Native Property DOM, bildirilmiş value, font, UI ve diğer property child'larını açığa çıkarır, yazılan field value'larını eşzamanlar ve font ölçümü ve desteklenen flatten styling'inde kullanılan instance-başına attribute'ları kalıcılaştırır

Yürüten node en yakın locale attribute'unu kalıtır; belge localeSet entry'leri sistem sembolleri ve pattern'lerini geçersiz kılar ve hesaplanan locale adları sınırlı dahili isteklerle çözümlenip session journal'inde korunur

Picture'sız Num2Date artık ambient default tarih pattern'ini kullanır; ISO çıktı gerektiğinde YYYY-MM-DD'yi açıkça sağlayın

Stateful host modeli

XFA Host Model, uygulama metadata'sını, gerçek sayfa sayısını, sayfa navigation'ını, Unicode title'ı, calculation/validation flag'lerini, scope'lu reset'i ve field focus'unu transactional enter/exit lifecycle'ıyla sağlar

TXFAWidgetRuntimeOptions.HostModel, başlangıç uygulama state'ini yapılandırır; TXFAWidgetRuntime.HostModel mevcut state'i döndürür ve başarısız event'ler onu belge ve etkileşim snapshot'larıyla birlikte geri yükler

Enter/exit script'siz, bekleyen edit'siz veya başlatılmış lifecycle'sız bir focus hareketi, script calculation'ını veya deadline işlemini başlatmadan focus'u değiştirir; script'li focus ve bekleyen-edit commit'leri yine de transactional bütçeler, validation ve yeniden hesaplama kullanır

Gelişmiş picture clause'ları, aynı runtime transaction'ları, locale retry journal'i ve calculation lifecycle'ı üzerinden — sınırlı bileşik parsing'le — yürütülür

Lifecycle'ı başlatın ve sürdürün

Runtime'ı ve callback'leri yapılandırdıktan sonra, initialize event'lerini template sırasında, ardından calculate ve validate'i, form-ready event'lerini ve layout-ready event'lerini yürütmek için InitializeForm'u çağırın; çağrı, başarıdan sonra idempotent'tir

Başlatma veya ready event'leriyle oluşturulan yeni instance'lar, ready handler'larından önce kendi initialize event'lerini alır; layout-ready yürütmesi, reflow ve transaction bütçeleri içinde yalnızca layout değiştiğinde tekrar eder

Başlatmadan sonra, başarılı event dispatch'i ve edit commit'i, yeni oluşturulan instance'ları başlatır ve calculate, validate ve layout-ready yürütür; mevcut occurrence'lar, başlatma state'lerini taşımalar ve transaction rollback boyunca korur

Lifecycle başarısızlıkları, belge baytlarını, widget etkileşimini ve başlatma defter tutmayı birlikte geri yükler ve callback'ler, kapsayan transaction başarılı olduktan sonra yayımlanır

Güncellenen formu kaydetme

SaveToBytes, runtime'ın eksiksiz güncellenmiş XDP'sini — değiştirilmiş dataset'ler ve standart instance-başına form state dâhil — döndürür; literal-parser presence değişiklikleri template attribute olarak kalır; bu baytları bir PDF yazarken SetXFADocument ile, güncellenmiş flatten çıktısı için HPDFXFAFlatten ile kullanın

Yüklenen belge factory'si bağımsız bir runtime oluşturur; böylece runtime event'leri kaynak PDF'in nesne grafiğini otomatik olarak değiştirmez

Opsiyonel instance presentation profili

Dynamic XFA Instance Presentation, açık tekrar-binding'leri, kararlı instance-başına ID'leri, indeksli presence ve access'i, sınırlı koşullu event'leri, host canvas painting'i ve erişilebilirliği bağımsız bir helper üzerinden ekler; default runtime ve kısıtlı event grameri uyumlu kalır

UpdateDocument, transactional belge action'ları sağlar; opsiyonel runtime property, binding-scope, identity, resolution-started ve belge-doğrulama callback'leri helper'ı desteklerken nil default'lar mevcut çağıranları korur

Alt-düzey event ve form API'leri

HPDFXFACompileFormCalcEvent event sözdizimini derler; HPDFXFAExecuteJavaScriptEvent, TXFAEventBinding ve TXFAEventBindings'in anlattığı sanal context'i yürütür

TXFAJavaScriptSession, alt-düzey çağıranlar için kalıcı yürütme ve sınırlı checkpoint'ler sağlar

Döndürülen TXFAEventAction value'ları, TXFAEventActionKind kullanır; transactional replay runtime tarafından sağlanır

HPDFXFAResolveFormInstanceNode ve HPDFXFAResolveFormInstanceProperty, sınırlı standart form-packet araması sağlar

Mevcut sınırlar

Runtime tek-thread bir host object'idir; GUI ve painting, host'un veya opsiyonel presentation helper'ın sorumluluğundadır

Focus girişi ve çıkışı, eşleşen bir event script yokken doğrudan desteklenir; kısıtlı event işlemleri, eksiksiz JavaScript, FormCalc, XFA yaşam döngüsü event'leri veya instance başına sunum override'lı ayrı bir form DOM desteği anlamına gelmez

Ayrıca bakınız: Sınırlı XFA FormCalc ve JavaScript, XFA Packet DOM ve Etkileşimli Belge İşleme