HPDFXFAExecuteJavaScriptEvent

Unit: HPDFXFAEventScript

Declaração

function HPDFXFAExecuteJavaScriptEvent(const Script: AnsiString;
  const Bindings: TXFAEventBindings; SelfIndex: Integer;
  const Options: TXFAFormScriptOptions; out Actions: TXFAEventActions;
  out Operations: Integer; out Diagnostic: string;
  Session: TXFAJavaScriptSession= nil;
  HostTransaction: TXFAHostTransaction= nil;
  LocaleProvider: TXFALocaleDataProvider= nil;
  HostModel: PXFAHostModelState= nil): Boolean;

Comportamento

Executa um evento contra um DOM virtual vivo de formulários e retorna records validados de mutações sem modificar o documento do chamador

Bindings fornecem o contexto do host e SelfIndex seleciona this; Options.EnableJavaScript precisa ser True

Texto de scripts e bindings raw são bytes UTF-8, decodificados explicitamente para a origem JavaScript e o contexto entre aspas, em vez de serem interpretados pela code page ANSI do sistema operacional; grego literal, scalars suplementares e separadores de linhas Unicode retêm seu valor exato

Usa o engine QuickJS delimitado embarcado ou Options.JavaScriptEvaluator, com orçamentos de scripts, contexto, memória, stack, interrupções, tempo, operações e saída

Retorna True apenas quando a execução do engine e a validação da saída têm sucesso; execução com falha limpa Actions e reporta Diagnostic

TXFAWidgetRuntime valida e reproduz as actions dentro da própria transação de snapshots dele; chamadores diretos precisam fornecer handling transacional equivalente

O engine nativo compila o código reutilizável de suporte a eventos uma vez por engine de sessão, enquanto cada chamada fornece seu vetor atual de bindings, corpo do evento, limites e respostas registradas de host, locale, cálculo e XML; sessões separadas e objetos de scripts repetidos retêm estado independente

Inicialização de suporte, execução de eventos, retries de suspensão e reconstrução de rollback compartilham o deadline original de tempo decorrido; callbacks customizados de JavaScriptEvaluator recebem um wrapper standalone completo

Passe um TXFAJavaScriptSession próprio para reter objetos de scripts e estado lexical entre chamadas; uma sessão nil cria um engine isolado para aquela chamada

Passe um TXFAHostTransaction próprio para efeitos explícitos da aplicação; retries de suspensão restauram o checkpoint da sessão e consomem as respostas registradas sem invocar de novo requisições completadas

Chamadores de nível mais baixo precisam finalizar a transação do host com o outcome do documento deles; efeitos do host exigem o engine embarcado e não podem usar JavaScriptEvaluator

LocaleProvider fornece metadados read-only de locales; nil usa os dados de locales do Windows, enquanto TXFAWidgetRuntime fornece o localeSet atual do documento com fallback do sistema

O binding Locale não vazio mais próximo fornece o locale ambiente; uma cadeia herdada vazia seleciona o locale atual do usuário

Nomes de locales computados suspendem a execução nativa, restauram o checkpoint da sessão e tentam de novo com os metadados registrados; o replay commitado consome esses metadados sem invocar o provider de novo

Cada chamada permite no máximo 64 requisições nomeadas de locales, 256 code units UTF-16 por identificador e 2 MiB de metadados de locales, compartilhando o deadline de tempo decorrido dos scripts; callbacks customizados de JavaScriptEvaluator precisam consumir os dados de locales fornecidos sem solicitar lookups nativos

HostModel fornece um snapshot read-only de metadados da aplicação, páginas, flags, título e focus; nil usa TXFAHostModelState.Default, e as actions retornadas de host/focus/reset exigem aplicação nativa transacional pelo chamador

O Eval dinâmico do FormCalc suspende para compilação nativa e tenta de novo com as respostas compiladas registradas dentro do mesmo deadline; callbacks customizados de JavaScriptEvaluator não conseguem atender essas requisições

O ponteiro é lido sincronamente e nunca é retido nem gravado; TXFAWidgetRuntime passa seu estado atual e aplica as mutações dentro da transação de snapshots de documento dele

O EventActivity do binding em execução fornece xfa.event.name, com event como fallback de nível mais baixo

A resolução SOM viva usa a hierarquia de bindings e a ordem atual de ocorrências, suporta selectors de classes e descendentes e predicados de candidatos, e seleciona uma ocorrência inferida ou default quando um índice é omitido

Os bindings do Data DOM constroem a tree de datasets, conectam valores de formulários através de DataIdentity e suportam escritas de dados e handles nativos retidos de dados; chamadores diretos aplicam ambos os domínios e as actions de identidades virtuais transacionalmente

Os bindings do DOM de propriedades expõem filhos declarados de propriedades e Attributes/DefaultAttributes; chamadores diretos aplicam as actions de raw-value e atributos de propriedades à ocorrência nativa correspondente de formulário

Aliases nomeados de campos são visíveis pelo escopo externo do evento; declarações locais de const, let, class, function e var seguem as regras lexicais normais do JavaScript dentro do corpo do evento

O corpo do evento preserva uma diretiva use strict inicial, seu contexto this de nó de formulário e valores de retorno explícitos; falhas lexicais ou de strict mode rejeitam a mesma transação nativa

Veja Escopo de eventos JavaScript para o comportamento de shadowing e persistência

APIs relacionadas

Runtime interativo de widgets XFA dinâmicos, Funções FormCalc e XFA Packet DOM