1. IronPDF
  2. Tutoriais
  3. Preencha formulários em PDF

Como preencher campos de formulário PDF em Node.js

Curtis Chau
Curtis Chau
Atualizado:
This article was translated from English: Does it need improvement?
Translated
View the article in English

Preencher formulários PDF programaticamente em Node.js permite automatizar fluxos de trabalho de documentos: desde o preenchimento de formulários de inscrição com registros de banco de dados até a geração de certificados personalizados em grande escala. O IronPDF for Node.js fornece uma API simples para carregar PDFs existentes, inserir valores em campos de formulário e salvar os documentos concluídos sem sair do seu ambiente JavaScript .

Este guia abrange todo o fluxo de trabalho: instalação do pacote, aplicação de uma chave de licença, preenchimento de campos de texto, caixas de seleção, listas suspensas e botões de opção, transformação de campos de formulário em campos fixos para bloquear valores e salvamento do resultado. Todos os exemplos de código usam await e o pacote @ironsoftware/ironpdf.

Início rápido: Preencha um formulário PDF em Node.js

Instale o pacote e, em seguida, carregue e preencha um formulário em poucas linhas:

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/install.sh
npm install @ironsoftware/ironpdf
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/install.sh
npm install @ironsoftware/ironpdf
SHELL 
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/quickstart.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = "YOUR-LICENSE-KEY-HERE";

(async () => {
    const pdf = await PdfDocument.fromFile("./form.pdf");
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("email", "jane@example.com");
    await pdf.saveAs("./filled-form.pdf");
})();
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/quickstart.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = "YOUR-LICENSE-KEY-HERE";

(async () => {
    const pdf = await PdfDocument.fromFile("./form.pdf");
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("email", "jane@example.com");
    await pdf.saveAs("./filled-form.pdf");
})();
JAVASCRIPT

Fluxo de trabalho mínimo (5 etapas)

1. Instale o IronPDF: `npm install @ironsoftware/ironpdf` 2. Defina sua chave de licença através de `IronPdfGlobalConfig.getConfig().licenseKey` 3. Carregue o PDF existente com `PdfDocument.fromFile(path)` 4. Defina o valor de cada campo com `await pdf.setFormFieldValue(fieldName, value)` 5. Salve o resultado com `await pdf.saveAs(outputPath)`

Quais são os pré-requisitos para preencher formulários PDF em Node.js?

Antes de executar os exemplos de código abaixo, confirme se três coisas estão em vigor: uma versão compatível do Node.js , uma chave de licença do IronPDF e o binário IronPdfEngine.

Versão do Node.js : O IronPDF requer o Node.js versão 18 ou superior. Faça o download da versão LTS atual no site oficial do Node.js A biblioteca usa E/S assíncrona do Node.js para todas as operações de PDF, portanto, o encadeamento de Promises (await) é o padrão em toda a biblioteca. Versões antigas do Node.js não são suportadas porque o pacote depende de recursos nativos do ESM e do async_hooks que exigem o Node.js 18+.

Chave de licença : Uma chave de licença IronPDF ativa desbloqueia a API completa. Inicie um teste gratuito para obter uma chave para desenvolvimento e testes ou compre uma licença para uso em produção. Para opções de implantação (variáveis ​​de ambiente, arquivos de configuração, gerenciadores de segredos), consulte o guia Usando Chaves de Licença .

IronPdfEngine : O pacote Node.js inclui IronPdfEngine, um mecanismo de renderização multiplataforma que lida com a manipulação real do PDF. As instruções de configuração e as informações específicas para cada plataforma (Windows, Linux, macOS) estão na documentação "Usar o IronPdfEngine" .

Como faço para definir a chave de licença no código Node.js ?

Aplique a chave de licença uma única vez na inicialização do aplicativo, antes de qualquer chamada PdfDocument:

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/license-setup.js
const { IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

// Apply once at startup -- before any PdfDocument operations
IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/license-setup.js
const { IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

// Apply once at startup -- before any PdfDocument operations
IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;
JAVASCRIPT

Armazenar a chave em uma variável de ambiente (como mostrado acima com process.env.IRONPDF_LICENSE_KEY) impede que as credenciais sejam incluídas no controle de versão. A Visão Geral de Introdução aborda padrões de inicialização adicionais para diferentes ambientes de implantação.

Como faço para instalar o IronPDF for Node.js?

A instalação do IronPDF for Node.js requer apenas um comando npm. Execute-o no diretório do seu projeto:

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/install-full.sh
npm install @ironsoftware/ironpdf
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/install-full.sh
npm install @ironsoftware/ironpdf
SHELL

O pacote é fornecido com declarações de tipo TypeScript , para que os projetos TypeScript obtenham suporte completo ao IntelliSense sem um pacote @types separado. Os binários específicos para cada plataforma (Windows, Linux e macOS) são baixados automaticamente durante a instalação. O pacote @Iron Iron Software/ IronPDF no npm lista todas as versões publicadas e dependências de mesmo nível.

ObservePara projetos TypeScript , as declarações incluídas .d.ts significam que o IntelliSense funciona imediatamente no VS Code e em outros editores que suportam serviços de linguagem TypeScript .

Para obter instruções sobre como adicionar o IronPDF a um monorepo existente ou a um fluxo de trabalho baseado em Docker, consulte a documentação do IronPDF for Node.js

Como preencher formulários PDF programaticamente?

Carregar um PDF e escrever valores em seus campos de formulário requer três chamadas assíncronas: PdfDocument.fromFile(), setFormFieldValue() e saveAs(). O exemplo abaixo preenche um formulário de inscrição com vários campos e, opcionalmente, o transforma em um documento plano para que os valores não possam ser alterados após o envio.

Como seria um exemplo completo de preenchimento de formulário?

O exemplo a seguir carrega um PDF com vários tipos de campos, preenche-os e salva o resultado. Para uma visão mais detalhada sobre como criar formulários em vez de preenchê-los, consulte a página de exemplos de formulários em PDF .

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/fill-pdf-form.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillApplicationForm() {
    // Load the PDF containing form fields
    const pdf = await PdfDocument.fromFile("./forms/application-form.pdf");

    // Discover available field names before filling
    const fieldNames = await pdf.getFormFieldNames();
    console.log("Form fields:", fieldNames);

    // Text fields
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("lastName", "Doe");
    await pdf.setFormFieldValue("email", "jane.doe@example.com");
    await pdf.setFormFieldValue("phone", "+1-555-987-6543");

    // Date field
    await pdf.setFormFieldValue("dateOfBirth", "03/22/1988");

    // Caixa de Seleção fields -- pass "true" or "false" as strings
    await pdf.setFormFieldValue("agreeToTerms", "true");
    await pdf.setFormFieldValue("subscribeNewsletter", "false");

    // Dropdown / select field
    await pdf.setFormFieldValue("country", "United States");

    // Multi-line text area
    await pdf.setFormFieldValue("comments", "Application submitted via automated workflow.");

    // Flatten the form to lock values -- prevents further editing
    // await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/filled-application.pdf");
    console.log("Form saved.");
}

fillApplicationForm().catch(console.error);
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/fill-pdf-form.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillApplicationForm() {
    // Load the PDF containing form fields
    const pdf = await PdfDocument.fromFile("./forms/application-form.pdf");

    // Discover available field names before filling
    const fieldNames = await pdf.getFormFieldNames();
    console.log("Form fields:", fieldNames);

    // Text fields
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("lastName", "Doe");
    await pdf.setFormFieldValue("email", "jane.doe@example.com");
    await pdf.setFormFieldValue("phone", "+1-555-987-6543");

    // Date field
    await pdf.setFormFieldValue("dateOfBirth", "03/22/1988");

    // Caixa de Seleção fields -- pass "true" or "false" as strings
    await pdf.setFormFieldValue("agreeToTerms", "true");
    await pdf.setFormFieldValue("subscribeNewsletter", "false");

    // Dropdown / select field
    await pdf.setFormFieldValue("country", "United States");

    // Multi-line text area
    await pdf.setFormFieldValue("comments", "Application submitted via automated workflow.");

    // Flatten the form to lock values -- prevents further editing
    // await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/filled-application.pdf");
    console.log("Form saved.");
}

fillApplicationForm().catch(console.error);
JAVASCRIPT

Após chamar getFormFieldNames(), a matriz retornada informa quais nomes de campo o autor do PDF utilizou. Esta é a maneira mais rápida de evitar erros de digitação nos nomes dos campos ao integrar com formulários que você não criou.

PontasChame getFormFieldNames() uma vez durante o desenvolvimento para imprimir os nomes exatos dos campos em seu PDF. Codificar o nome errado diretamente no código é a causa mais comum de campos aparecerem vazios após setFormFieldValue().

Como faço para lidar com diferentes tipos de campos de formulário?

O IronPDF suporta os tipos de campo padrão do AcroForm: caixas de texto, caixas de seleção, botões de opção, listas suspensas, caixas de listagem e campos de assinatura. O método setFormFieldValue() aceita valores de string para todos os tipos; para campos de caixa de seleção e de opção, os valores aceitos dependem da definição específica do campo no PDF.

A tabela abaixo mostra o formato de valor para cada tipo de campo:

Tipos de campos do PDF AcroForm e seus formatos de valores aceitos
Tipo de CampoFormato do valorExemplo
Texto / MultilinhasQualquer string"Jane Doe"
Caixa de Seleção"true" ou "false""true"
Botão de opçãoValor de exportação da opção"Female"
Menu suspenso (Combo)Exibir o texto da opção"United States"
Caixa de listagem (seleção múltipla)Matriz de strings["Option1", "Option2"]
Data / NuméricoRepresentação em string"2024-06-15"

Como funcionam as caixas de seleção e os botões de opção?

As caixas de seleção aceitam "true" para marcar e "false" para desmarcar. Os botões de opção aceitam o valor de exportação da opção selecionada — a string exportada geralmente fica visível nas propriedades do campo do PDF e é diferente do rótulo de exibição.

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/field-types.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function handleFieldTypes() {
    const pdf = await PdfDocument.fromFile("./forms/complex-form.pdf");

    // Radio button -- use the field's export value, not its display label
    await pdf.setFormFieldValue("gender", "Female");

    // Caixa de Seleção
    await pdf.setFormFieldValue("termsAccepted", "true");

    // Dropdown
    await pdf.setFormFieldValue("preferredContact", "Email");

    // Numeric field -- pass the number as a string
    await pdf.setFormFieldValue("invoiceAmount", "1250.00");

    // Date picker
    await pdf.setFormFieldValue("appointmentDate", "2024-06-15");

    await pdf.saveAs("./output/complex-form-filled.pdf");
}

handleFieldTypes().catch(console.error);
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/field-types.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function handleFieldTypes() {
    const pdf = await PdfDocument.fromFile("./forms/complex-form.pdf");

    // Radio button -- use the field's export value, not its display label
    await pdf.setFormFieldValue("gender", "Female");

    // Caixa de Seleção
    await pdf.setFormFieldValue("termsAccepted", "true");

    // Dropdown
    await pdf.setFormFieldValue("preferredContact", "Email");

    // Numeric field -- pass the number as a string
    await pdf.setFormFieldValue("invoiceAmount", "1250.00");

    // Date picker
    await pdf.setFormFieldValue("appointmentDate", "2024-06-15");

    await pdf.saveAs("./output/complex-form-filled.pdf");
}

handleFieldTypes().catch(console.error);
JAVASCRIPT

Os campos de caixa de listagem de seleção múltipla seguem o mesmo padrão. Quando um campo permite múltiplas seleções, passe uma matriz de strings em vez de um único valor. Os campos de assinatura podem receber uma sequência de imagem codificada em base64 representando o gráfico da assinatura.

ImportanteSe setFormFieldValue() não alterar o valor de um campo, verifique se o nome do campo corresponde exatamente -- os nomes de campos em PDF diferenciam maiúsculas de minúsculas. Use getFormFieldNames() para listar os nomes reais no documento.

Como faço para achatar os campos de um formulário PDF após o preenchimento?

Ao achatar um formulário PDF, todos os valores dos campos são incorporados ao conteúdo estático da página, removendo a camada interativa. O documento resultante não pode ser editado posteriormente, o que evita alterações acidentais durante a distribuição e garante uma renderização consistente em todos os visualizadores de PDF.

Chame o código flattenAllFormFields() no documento carregado após definir todos os valores dos campos e antes de salvar:

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/flatten-form.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillAndFlattenForm() {
    const pdf = await PdfDocument.fromFile("./forms/contract.pdf");

    // Fill the required fields
    await pdf.setFormFieldValue("signerName", "Jane Doe");
    await pdf.setFormFieldValue("signatureDate", "2024-06-15");
    await pdf.setFormFieldValue("agreementAccepted", "true");

    // Flatten -- converts interactive fields to static content
    await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/contract-signed.pdf");
    console.log("Contract flattened and saved.");
}

fillAndFlattenForm().catch(console.error);
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/flatten-form.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillAndFlattenForm() {
    const pdf = await PdfDocument.fromFile("./forms/contract.pdf");

    // Fill the required fields
    await pdf.setFormFieldValue("signerName", "Jane Doe");
    await pdf.setFormFieldValue("signatureDate", "2024-06-15");
    await pdf.setFormFieldValue("agreementAccepted", "true");

    // Flatten -- converts interactive fields to static content
    await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/contract-signed.pdf");
    console.log("Contract flattened and saved.");
}

fillAndFlattenForm().catch(console.error);
JAVASCRIPT

O alisamento é apropriado para entregas finais — contratos após a assinatura, certificados após a emissão ou faturas após a aprovação. Para documentos que precisam de revisão adicional antes da finalização, ignore flattenAllFormFields() e salve sem ele.

AvisoO achatamento é irreversível na cópia salva. Guarde o PDF original, em branco, como modelo caso precise gerar o documento novamente.

Quais são os casos de uso mais comuns para a automação de formulários em PDF?

O preenchimento automático de formulários elimina a entrada manual de dados em fluxos de trabalho com grande volume de documentos. Os cenários a seguir abrangem os padrões mais frequentes que os desenvolvedores implementam com o IronPDF.

Processamento de candidaturas : Extrai dados de candidatos de um banco de dados ou API REST e preenche formulários PDF para serviços financeiros, seguros ou fluxos de trabalho de admissão governamentais. Combine os formulários preenchidos usando o exemplo "Mesclar PDFs" para produzir um único pacote de envio com várias páginas.

Geração de faturas e recibos : Preencha modelos de faturas com dados de itens de linha, detalhes do cliente e totais calculados. Adicione cabeçalhos e rodapés de página usando as técnicas mostradas no exemplo de Cabeçalhos e Rodapés HTML .

Geração de certificados e credenciais : Personalize modelos de certificados com nomes dos destinatários, datas de conclusão e títulos dos cursos. Adicione segurança usando o exemplo de Assinaturas Digitais para evitar adulteração após a emissão. O padrão PDF/A é geralmente exigido para o arquivamento a longo prazo de certificados em setores regulamentados.

Geração de relatórios : Preencha os modelos de relatório com dados analíticos ou resultados de pesquisas. Para casos em que você precise criar o layout do PDF do zero, em vez de preencher um formulário existente, consulte o tutorial de HTML para PDF .

Quais são os próximos passos para o preenchimento de formulários PDF em Node.js?

Este guia demonstrou como carregar um PDF, preencher campos de texto, caixas de seleção, listas suspensas e botões de opção, achatar o formulário para bloquear os valores e salvar o documento concluído. A mesma instância PdfDocument suporta outras operações -- adicionar assinaturas digitais, compactar a saída ou extrair texto -- sem recarregar o arquivo.

Inicie um teste gratuito para experimentar o IronPDF no seu projeto ou veja as opções de licenciamento para encontrar o plano ideal para a sua implementação.

Pronto para ver o que mais você pode fazer? Confira a coleção completa de tutoriais de Node.js aqui: HTML para PDF em Node.js

Perguntas frequentes

Quais são os pré-requisitos para preencher formulários PDF em Node.js?

Você precisa do Node.js 18 ou superior, uma chave de licença IronPDF (uma avaliação gratuita está disponível) e o binário IronPdfEngine. O motor é integrado ao pacote @ironsoftware/ironpdf e baixado automaticamente durante a instalação.

Como faço para instalar o IronPDF for Node.js?

Execute npm install @ironsoftware/ironpdf no diretório do seu projeto. O comando instala o pacote e seus binários específicos à plataforma para Windows, Linux e macOS. Declarações de tipo TypeScript estão incluídas.

Como descubro os nomes dos campos em um formulário PDF?

Chame await pdf.getFormFieldNames() após carregar o PDF com PdfDocument.fromFile(). O método retorna um array de todas as strings de nomes de campo do documento. Os nomes dos campos PDF são sensíveis a maiúsculas e minúsculas, por isso use as strings exatas retornadas.

Em que formato os valores de caixas de seleção e botões de rádio são aceitos?

As caixas de seleção aceitam a string "true" para marcar e "false" para desmarcar. Botões de rádio aceitam o valor exportado da opção alvo como string. Use getFormFieldNames() e inspecione as propriedades do campo PDF para encontrar o valor de exportação correto.

Como evito que um formulário PDF preenchido seja editado?

Chame await pdf.flattenAllFormFields() após definir todos os valores dos campos e antes de saveAs(). Achatar mescla os valores dos campos no conteúdo de página estático e remove a camada de formulário interativo. A operação é irreversível no arquivo salvo.

Posso usar o IronPDF for Node.js com TypeScript?

Sim. O pacote @ironsoftware/ironpdf vem com declarações TypeScript (arquivos .d.ts), então você tem verificação de tipos completa e IntelliSense no VS Code e outros editores sem precisar instalar um pacote de tipos separados.

Curtis Chau
Curtis Chau
  Converse agora mesmo com a equipe de engenharia.
Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais ...

Leia mais
Pronto para começar?
Versão: 2026.5 just released
Still Scrolling Icon

Ainda está rolando a tela?

Quer provas rápidas?
executar um exemplo Veja seu HTML se transformar em um PDF.