Ler valores de campos de formulário PDF por tipo com JavaScript

Quando alguém preenche um formulário PDF e o salva, os valores inseridos ficam dentro das estruturas de campos do documento — não como texto simples que você possa pesquisar ou copiar em massa. Para um formulário com trinta ou quarenta campos, a transcrição manual torna-se um gargalo. O problema mais profundo é que cada tipo de campo armazena seu valor de maneira diferente: uma caixa de texto expõe uma string, uma caixa de seleção reporta um booleano, uma caixa de combinação separa as opções da seleção, e um botão de opção armazena o item escolhido. Não existe uma única chamada uniforme de "me dê o valor".

Este artigo mostra como extrair valores de campos de formulário de um PDF usando o Spire.PDF for JavaScript. A biblioteca é executada em WebAssembly no navegador, então o documento é analisado localmente por meio de um sistema de arquivos virtual, sem ida e volta ao servidor. Você verá como percorrer a coleção de campos, identificar o tipo de cada campo e ler a propriedade correta para caixas de texto, caixas de lista, caixas de combinação, botões de opção e caixas de seleção.

Para configuração e instalação do projeto, consulte Integrate Spire.PDF for JavaScript in a React Project. O código abaixo pressupõe que o Spire.PDF está instalado e o módulo WASM está inicializado.

Tipos de Campo em Resumo

Antes de mergulhar na implementação, ajuda mapear como cada tipo de campo expõe seu valor. O Spire.PDF for JavaScript representa campos de formulário como classes de widget, e a propriedade que contém o valor atual difere de um tipo para outro:

O padrão é claro: não existe uma única propriedade universal. A lógica de extração deve testar o tipo de cada campo e ler a propriedade correspondente, que é exatamente o que a próxima seção implementa.

Iterar Campos e Ler por Tipo

O fluxo de trabalho principal tem três etapas: carregar o PDF, obter seu formulário como um PdfFormWidget e então percorrer a coleção FieldsWidget e ramificar pelo tipo de cada campo com instanceof. Em cada ramificação, leia a propriedade específica do tipo e acrescente o resultado a uma string de relatório. Como a distribuição cobre todos os tipos suportados, você não precisa saber de antemão quais campos o documento contém — campos não reconhecidos simplesmente caem em um rótulo padrão.

function App() {
  const getAllFieldValues = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // Load the PDF file to be read into the VFS
    const inputFileName = 'ApplicationForm.pdf';
    await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}/data/`);

    // Create a PdfDocument object and load the PDF document
    const doc = new pdfModule.PdfDocument();
    doc.LoadFromFile(inputFileName);

    // Build a PdfFormWidget from the document's form handle; FieldsWidget is its field collection
    const formWidget = new pdfModule.PdfFormWidget(doc.Form.H);
    const fields = formWidget.FieldsWidget;

    let report = '';

    // Walk the field collection, check each type, and read the matching value
    for (let i = 0; i < fields.Count; i++) {
      const field = fields.get_Item({ index: i });

      // Both the type name and the value are filled in by the type dispatch
      let type = 'Unknown';
      let value = '(Unrecognized field type)';

      if (field instanceof pdfModule.PdfTextBoxFieldWidget) {
        // Text box field: read Text directly
        type = 'TextBox';
        value = field.Text;
      } else if (field instanceof pdfModule.PdfListBoxWidgetFieldWidget) {
        // List box field: Values holds every option, SelectedValue is the current one
        const options = [];
        for (let j = 0; j < field.Values.Count; j++) {
          options.push(field.Values.get_Item(j).Value);
        }
        type = 'ListBox';
        value = `Selected ${field.SelectedValue}, options ${options.join(', ')}`;
      } else if (field instanceof pdfModule.PdfComboBoxWidgetFieldWidget) {
        // Combo box field: like a list box, it has an option collection and a selected value
        const options = [];
        for (let j = 0; j < field.Values.Count; j++) {
          options.push(field.Values.get_Item(j).Value);
        }
        type = 'ComboBox';
        value = `Selected ${field.SelectedValue}, options ${options.join(', ')}`;
      } else if (field instanceof pdfModule.PdfRadioButtonListFieldWidget) {
        // Radio button field: Value is the selected item
        type = 'RadioButton';
        value = `Selected ${field.Value}`;
      } else if (field instanceof pdfModule.PdfCheckBoxWidgetFieldWidget) {
        // Check box field: Checked gives the state, not Value
        type = 'CheckBox';
        value = field.Checked ? 'Checked' : 'Not checked';
      }

      report += `Field "${field.Name}" (${type}): ${value}\n`;
    }

    const outputFileName = 'AllFieldValues.txt';
    window.dotnetRuntime.Module.FS.writeFile(outputFileName, report);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/plain' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Extract Form Field Values</h1>
      <button onClick={getAllFieldValues}>
        Extract values
      </button>
    </div>
  );
}

export default App;

Depois que o loop termina, a string de relatório contém uma linha por campo com seu nome, tipo e valor atual. O arquivo é gravado no sistema de arquivos virtual e então baixado como um arquivo de texto:

A cadeia de instanceof é o coração da abordagem. Cada ramificação sabe exatamente qual propriedade ler, então a saída fica correta independentemente de quantos tipos de campo o documento mistura. As próximas três seções abordam as armadilhas que surgem quando a propriedade de valor de um campo não é a que você poderia esperar.

Caixas de Seleção: Checked vs Value

Um erro comum ao ler campos de caixa de seleção é recorrer a uma propriedade Value. O widget de caixa de seleção — PdfCheckBoxWidgetFieldWidget — não expõe Value de forma alguma; tentar lê-lo retorna undefined. Nos bastidores, uma caixa de seleção rastreia seu estado por meio de valores de exportação: Off quando não marcada, e Yes ou uma string de exportação personalizada quando marcada. Uma string bruta não consegue dizer de forma confiável se a caixa está selecionada, então a superfície da API deliberadamente omite Value e oferece Checked em vez disso.

A correção é simples — use sempre a propriedade booleana Checked:

// Check the state with Checked, not Value
const checked = field.Checked;

Isso retorna true quando a caixa está marcada e false caso contrário, fornecendo um booleano limpo para a lógica subsequente, sem qualquer análise de string.

Caixas de Lista e Caixas de Combinação: SelectedValue vs Values

Caixas de lista e caixas de combinação compartilham um modelo de dados em duas partes que confunde muitos desenvolvedores. Tanto PdfListBoxWidgetFieldWidget quanto PdfComboBoxWidgetFieldWidget expõem uma coleção Values e uma string SelectedValue, e é fácil supor que Values contém a entrada do usuário. Não contém.

Values é o conjunto completo de opções disponíveis. Cada elemento da coleção é um objeto PdfListWidgetItem, então você deve desempacotá-lo com .Value para obter o texto da opção. Percorrer Values informa o que o usuário poderia ter escolhido, não o que ele realmente selecionou. A seleção real do usuário está em SelectedValue como uma string simples.

Use SelectedValue para o valor atual e percorra Values apenas quando precisar enumerar as escolhas disponíveis:

// The text of the currently selected item
const selected = field.SelectedValue;

// Every available option
const options = [];
for (let j = 0; j < field.Values.Count; j++) {
  options.push(field.Values.get_Item(j).Value);
}

Manter essas duas propriedades bem distintas é essencial: tratar Values como a resposta fornece a lista de opções em vez do resultado preenchido, e as duas raramente têm o mesmo comprimento.

Lidar com PDFs Criptografados

A extração de formulário começa abrindo o documento. Se o PDF estiver protegido por senha, chamar LoadFromFile apenas com o nome do arquivo lança um erro — "Can not open an encrypted document. The password is invalid." — e nenhum objeto de documento é retornado. Os campos de formulário nunca são alcançados.

A solução é passar a senha de abertura como o segundo argumento:

doc.LoadFromFile(inputFileName, 'spire123');

Depois que o documento abre com sucesso, o restante do fluxo de extração — construir o PdfFormWidget, percorrer os campos, distribuir por tipo — funciona exatamente da mesma forma que com um arquivo não criptografado. A senha apenas bloqueia o carregamento inicial; ela não altera como os valores dos campos são lidos.

Veja Também

• Integrate Spire.PDF for JavaScript in a React Project — configuração, instalação e inicialização do WASM
• Fill PDF Form Fields with Spire.PDF for JavaScript — gravar valores em campos de formulário programaticamente
• Import and Export PDF Form Data with Spire.PDF for JavaScript — serializar dados de formulário em arquivos FDF/XFDF

Se você quiser remover a mensagem de avaliação do documento resultante, ou eliminar as limitações de recursos, entre em contato com a equipe de vendas para obter uma licença temporária válida por 30 dias.