Uma caixa de comentários vazia num formulário XFA reabre guardando um line feed. Salve e reabra de novo e a caixa guarda dois. Um nome de cliente digitado com U+1F642, o rosto levemente sorridente, volta como U+F642, um code point de private use que a maioria das fontes desenha como um retângulo vazio. Os três efeitos moram no XML que um salvamento XFA grava no packet datasets, e um caminho de salvamento que acerta neles precisa manter whitespace de layout fora dos valores de campo, carregar caracteres do plano suplementar como pares surrogate completos e reportar uma gravação falha pelo resultado do salvamento em vez de por um arquivo danificado
Qual runtime do PDFium salva valores XFA?
Só a pdfium.v8.dll salva valores XFA, porque é o único build do PDFium Component que carrega tanto o motor JavaScript V8 quanto o runtime de formulários XFA. Uma vez que uma edição é commitada (o campo perdeu o foco, ou ClearFormFieldFocus forçou o commit), esse runtime exporta os dados XFA vivos para o packet datasets no salvamento, sem edição de packets no seu código. Cada arquitetura Windows também traz uma pdfium.dll, construída sem V8 e sem XFA, que grava os packets armazenados de volta exatamente como os leu. O que acontece com um valor gravado enquanto o campo ainda tem foco está coberto em por que edições de campos XFA desaparecem ao salvar
O wrapper Delphi tenta escolher a biblioteca certa para você. Quando EnableV8Engine ainda está False e nenhuma biblioteca PDFium foi carregada ainda, a TPdf olha o arquivo que está prestes a abrir e, se encontra marcadores XFA (uma entrada /XFA no dicionário AcroForm, ou /NeedsRendering true no catálogo), liga o EnableV8Engine antes de carregar. Essa troca só funciona uma vez por processo. Se uma pdfium.dll comum já está residente porque o primeiro documento da sessão era um PDF simples, o processo fica comprometido com ela, e TPdf.OnXfaRuntimeMissing dispara quando um documento XFA chega depois
A ordem de busca padrão é a outra metade do problema. Sem um diretório em LibraryName, o loader começa por uma pasta DLLs\Win32 ou DLLs\Win64 sob a pasta da aplicação ou um dos pais dela, então uma pdfium.v8.dll mais velha pode ser encontrada primeiro. Um LibraryName que contém um diretório fixa exatamente aquele arquivo, e se ele falta, a carga falha
uses
System.SysUtils, PDFium;
procedure SelectXfaRuntime;
begin
// Um diretório no LibraryName fixa exatamente este arquivo;
// um arquivo ausente faz o LoadLibrary falhar em vez de procurar em outro lugar
{$IFDEF WIN64}
PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win64\pdfium.v8.dll';
{$ELSE}
PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win32\pdfium.v8.dll';
{$ENDIF}
PDFium.EnableV8Engine := True;
PDFium.LoadLibrary; // falhe no startup, não no primeiro salvamento XFA
end;
Depois de um documento aberto, TPdf.XFA diz que o arquivo contém XFA, e TPdf.XfaRuntimeAvailable diz que a biblioteca carregada conseguiu de fato iniciar o motor XFA para este documento. Formulários estáticos e dinâmicos se distinguem por TPdf.FormType, que devolve ftXfaFull para um formulário dinâmico e ftXfaForeground para um estático. Sondagem em nível de packet numa máquina sem o runtime V8 é o assunto de detectar formulários XFA e extrair packets XFA em Delphi
Por que campos XFA salvos podem ganhar line feeds extras?
Campos XFA salvos ganham line feeds quando o escritor formata o XML com uma nova linha depois de cada tag de abertura. Dois escritores participam de um salvamento XFA, o escritor genérico de elementos XML e o serializador do packet de formulário, e ambos costumam formatar a saída desse jeito. Na maioria dos documentos XML esse whitespace é cosmético. Em dados XFA ele é o valor: quando o packet datasets é parseado de novo, todo caractere entre <Comments> e </Comments> pertence ao campo, nova linha incluída
Um campo vazio então reabre guardando um único LF. Cada salvamento seguinte formata em volta do LF já presente, então um campo que ninguém tocou cresce uma linha por rodada de revisão
Aparar valores na carga parece um reparo barato, e corromperia dados reais. As pessoas digitam espaços no início, espaços no fim e quebras de linha deliberadas em campos XFA; um bloco de endereço precisa manter a estrutura de linhas, e um código de referência de largura fixa precisa sobreviver byte a byte. Os escritores XFA do PDFium Component em vez disso descartam só o whitespace que o próprio serializador sintetiza em volta das tags. Valores do usuário, nós de texto que já estavam no arquivo e seções CDATA passam sem alteração, então " indented" continua indentado e um campo intencionalmente vazio continua vazio
Emoji, pares surrogate e um wchar_t de 16 bits
Um emoji volta como outro caractere quando um caminho de decodificação guarda um valor escalar Unicode completo num único wchar_t, que no Windows tem 16 bits. Dois pontos de uma carga XFA ficam expostos a isso: o decodificador do stream UTF-8 e o parser de referências de caractere numéricas como 🙂. U+1F642 precisa de 17 bits. Esprema-o em 16 e o bit superior cai, deixando U+F642 na Private Use Area
Um serializador de formulário pode falhar na direção oposta. Filtrando caracteres um wchar_t por vez, ele vê duas code units surrogate, D83D e DE42, cada uma inválida sozinha, e descarta as duas. O emoji desaparece do packet do formulário, sem caractere de substituição para trás
No PDFium Component o decodificador consome cada valor escalar por completo e emite um par surrogate próprio, inclusive quando o buffer de saída só tem espaço para mais uma unit e quando uma sequência UTF-8 de quatro bytes é dividida entre dois blocos de leitura. Na saída, o exportador de formulário mantém pares surrogate válidos juntos, e referências de caractere numéricas também decodificam para pares corretos
Dados de teste Latin-1 nunca tocam nenhum desses caminhos. Um teste de round trip para um formulário XFA precisa de pelo menos um caractere acima de U+FFFF num campo de texto, e conferir os bytes salvos pela sequência UTF-8 de quatro bytes F0 9F 99 82 diz mais que olhar o campo renderizado
XFA de stream único e o resultado do salvamento
Um documento XFA de stream único mantém as edições só se o caminho de salvamento conseguir reescrever um stream XDP no lugar, e qualquer entrada que ele não consiga reescrever precisa falhar o salvamento. A ISO 32000-1 §12.7.8 permite que a entrada /XFA do dicionário de formulário interativo seja um array que alterna nomes de packets e streams ou um único stream com o documento XDP inteiro. Um caminho de salvamento escrito só para arrays recusa streams únicos, e se quem chamou ignora esse resultado, o PDF é gravado com os dados do formulário nos valores antigos
O runtime V8 no PDFium Component trata um subconjunto definido de streams únicos em três passos. Ele exporta os dois packets vivos, datasets e form, para uma área de estágio e os valida. Só então substitui os packets correspondentes dentro do XDP original, mantendo os outros packets e as declarações de namespace da raiz. Se o estágio falha, o stream XFA persistente nunca é tocado e o documento mantém a marca de modificação, para um salvamento posterior tentar de novo
Comentários XML e processing instructions pedem cuidado extra, porque o parser usado na reescrita os descarta. Cada um é trocado por um marcador único antes do parse e recolocado depois, e o stream só é gravado se todo marcador aparece exatamente uma vez, então comentários fora dos packets vivos mantêm o texto e a ordem
Algumas entradas são recusadas de cara, e cada recusa chega até você como um salvamento falho:
- Comentários ou processing instructions dentro dos packets vivos
datasetsouform, já que não há como mapear as posições originais deles para o conteúdo recém-exportado - Declarações DTD e assinaturas XMLDSig, já que reescrever o XDP não consegue manter uma assinatura XML válida
- UTF-8 ou UTF-16 inválido, tags incompletas, referências de caractere inválidas, entidades desconhecidas e processing instructions malformadas, que são rejeitadas em vez de reparadas na correria
Recusar é a troca melhor aqui. Um salvamento que devolve False pode ser tentado de novo, registrado no log ou passado para uma pessoa, enquanto um XDP silenciosamente normalizado pode quebrar uma assinatura ou um importador a jusante semanas depois, longe do código que o mudou. O que o caminho de stream único preserva é o modelo de conteúdo XML, gravado em UTF-8; o layout de bytes original e a declaração de encoding do stream fonte não são carregados junto
O último bloco em buffer
A armadilha final fica abaixo do XFA, no escritor genérico de PDF. Um escritor de arquivos que faz buffer da saída em blocos de tamanho fixo precisa empurrar o último bloco parcial no fim. Se isso acontece em código de limpeza depois que o escritor do documento já reportou sucesso, um disco cheio ou um erro de I/O no último bloco nunca chega a quem chamou, e o arquivo no disco fica incompleto. Nos dois runtimes do PDFium Component o flush final faz parte do resultado do salvamento, e a marca de modificação XFA só é limpa depois que a gravação realmente teve sucesso
O lado Delphi adiciona mais uma camada. TPdf.SaveAs grava num arquivo temporário ao lado do alvo e o move por cima do alvo só quando o salvamento do stream devolve True. Um resultado False deixa o arquivo anterior exatamente como estava, e uma falha na substituição final levanta um erro do sistema operacional em vez de retornar em silêncio
Por que um formulário XFA dinâmico reabre com menos páginas?
Um formulário XFA dinâmico reabre com menos páginas quando o subform raiz dele não declara restoreState="auto", e essa decisão pertence ao autor do formulário. Na XFA 3.3, restoreState no subform raiz tem padrão manual. Sob manual, o processador XFA restaura só um estado limitado do packet de formulário salvo e deixa o resto para os scripts do próprio formulário. Valores de campo e contagens de instância de subforms repetidos voltam; propriedades geométricas definidas em run time não
Suponha um formulário de três páginas cujo script cresce um subform para h="450pt" enquanto o usuário o preenche. O packet de formulário salvo guarda a nova altura, os valores dos campos e as contagens de instância. Na reabertura, o layout é reconstruído a partir das alturas do template, o subform encolhe de volta, e o conteúdo reflui para duas páginas. Esse é o comportamento que a especificação XFA pede quando o template nunca pediu restauração automática. Declará-lo no subform raiz muda a reabertura:
<template xmlns="http://www.xfa.org/schema/xfa-template/3.3/">
<subform name="form1" layout="tb" restoreState="auto">
<pageSet>
<pageArea name="Page1">
<contentArea x="0.25in" y="0.25in" w="8in" h="10.5in"/>
<medium stock="letter"/>
</pageArea>
</pageSet>
<subform name="Details" layout="tb" w="7.5in">
<!-- fields; scripts podem mudar h ou adicionar instâncias em run time -->
</subform>
</subform>
</template>
Se o template não é seu, deixe-o em paz: um formulário construído para o modo manual espera que os próprios scripts de inicialização reconstruam o estado, e trocar o modo por baixo deles muda aquilo em volta do qual esses scripts foram escritos. Repaginação viva enquanto o usuário digita é outro mecanismo, descrito em como o PDFium Component acompanha contagens de página de XFA dinâmico e campos movidos
Conferindo um round trip XFA a partir do Delphi
Um salvamento XFA é verificado reabrindo o arquivo salvo numa instância nova de TPdf e lendo os dados armazenados de volta, já que um True do SaveAs só diz que o arquivo foi gravado. TPdf.GetXfaDatasets devolve o packet datasets como está armazenado no documento, não o modelo de dados vivo, então lê-lo antes do salvamento mostra os valores da última carga. Depois de uma reabertura, mostra exatamente o que foi gravado. Um documento de stream único não tem packets com nomes separados: o PDFium reporta o XDP inteiro como um packet de nome vazio, então GetXfaPacketByName('datasets') e GetXfaDatasets devolvem ambos um array vazio, e o código abaixo cai para o stream completo de GetXfaFormPackets
uses
System.SysUtils, PDFium, FPdfXfa;
function ReadSavedXfaData(const FileName: string): string;
var
Pdf: TPdf;
Packets: TXfaPacketList;
Bytes: TBytes;
begin
Pdf := TPdf.Create(nil);
try
Pdf.FileName := FileName;
Pdf.Active := True;
Bytes := Pdf.GetXfaDatasets; // layout de array de packets
if Length(Bytes) = 0 then
begin
Packets := Pdf.GetXfaFormPackets; // stream único: um packet sem nome
if Length(Packets) = 1 then
begin
SetLength(Bytes, Length(Packets[0].Content));
if Length(Bytes) > 0 then
Move(Packets[0].Content[0], Bytes[0], Length(Bytes));
end;
end;
Result := TEncoding.UTF8.GetString(Bytes); // a saída XDP salva é UTF-8
finally
Pdf.Free;
end;
end;
A rotina de salvamento commita a edição pendente, confere o resultado do SaveAs e compara o valor reaberto. TPdf.ClearFormFieldFocus remove o foco do formulário, que é quando o PDFium commita o buffer de edição do campo com foco. TPdf.SetFocusedFormFieldText preenche o campo com foco a partir do código, mas depende de foco acompanhado por widget annotations, que uma página XFA dinâmica normalmente não tem; ali ele devolve False, e o texto normalmente chega por entrada de teclado no TPdfView
// XmlText é um helper que você adiciona; não faz parte do PDFium Component
function XmlText(const S: string): string;
begin
Result := StringReplace(S, '&', '&', [rfReplaceAll]);
Result := StringReplace(Result, '<', '<', [rfReplaceAll]);
end;
procedure SaveXfaAndVerify(Pdf: TPdf; const FileName, FieldTag,
Expected: string);
var
Saved: string;
begin
// Preenchimento scriptado opcional; False significa que nenhum campo acompanhado tem foco
if (Pdf.FocusedFormFieldIndex >= 0) and
not Pdf.SetFocusedFormFieldText(Expected) then
raise EPdfError.Create('Could not write the focused field');
Pdf.ClearFormFieldFocus; // commita o buffer de edição
if not Pdf.SaveAs(FileName) then // False: arquivo anterior fica no lugar
raise EPdfError.CreateFmt('Saving %s failed', [FileName]);
// Reabra numa TPdf nova e procure o texto exato do elemento
Saved := ReadSavedXfaData(FileName);
if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
Saved) = 0 then
raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;
O teste de substring é só um smoke test. Um elemento vazio pode ser gravado como <Tag/>, elementos de dados podem carregar atributos, e o escaping além de & e < fica por conta do serializador, então verificações de produção pertencem a um parser XML de verdade. Rode a rotina duas vezes seguidas com a mesma entrada, porque a deriva de novas linhas só mostra a forma completa na segunda geração
Aplicações hospedeiras que comandam o runtime XFA diretamente também precisam do layout de callbacks que ele espera, que é o tema de FPDF_FORMFILLINFO versão 2 e o ABI XFA em Delphi. Ambos os runtimes Windows para Win32 e Win64, o wrapper Delphi e C++Builder e o controle de visualização TPdfView acompanham o PDFium Component for Delphi and C++Builder