如何在Node.js中填写PDF表单字段

Q: 如何安装 IronPDF for Node.js？

在项目目录中运行 npm install @ironsoftware/ironpdf 。该命令将安装该包及其适用于Windows、Linux和macOS的平台特定二进制文件。TypeScript类型声明已包含在内。

Q: 如何发现PDF表单中的字段名？

在使用 PdfDocument.fromFile() 加载PDF后，调用 await pdf.getFormFieldNames() 。该方法返回文档中所有字段名称字符串的数组。PDF字段名区分大小写，因此请使用返回的确切字符串。

Q: 复选框和单选按钮接受什么值格式？

复选框接受字符串 "true" 和 "false" 以选中和未选中。单选按钮接受目标选项的导出值字符串。使用 getFormFieldNames() 并检查PDF字段属性以找出正确的导出值。

Q: 如何防止填写完的PDF表单被编辑？

在设置所有字段值并在 saveAs() 之前，调用 await pdf.flattenAllFormFields() 。展平操作将字段值合并为静态页面内容，并移除交互式表单层。此操作在保存的文件上不可逆。

Q: 我可以在Node.js中将IronPDF与TypeScript一起使用吗？

可以。 @ironsoftware/ironpdf 包内含有TypeScript声明（ .d.ts 文件），因此您可以在VS Code和其他编辑器中进行完整类型检查和IntelliSense，而无需安装单独的类型包。

Curtis Chau

Updated: 2026年6月4日

在Node.js中以编程方式填写PDF表单可让您自动化文档工作流：从用数据库记录填充申请表到大规模生成个性化证书。 IronPDF for Node.js为加载现有PDF、在表单字段中写入值并在不离开JavaScript环境下保存完整文档提供了一个简单的API。

本指南涵盖整个工作流程：安装包、申请许可证密钥、填充文本字段、复选框、下拉菜单和单选按钮、平展表单字段以锁定值和保存输出。所有代码示例使用@ironsoftware/ironpdf包。

快速入门：在Node.js中填写PDF表单

安装包，然后在几行代码中加载并填充表单：

//: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

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");
})();

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

最小工作流程（5 个步骤）

安装IronPDF: npm install @ironsoftware/ironpdf
使用IronPdfGlobalConfig.getConfig().licenseKey设置您的许可证密钥
使用PdfDocument.fromFile(path)加载现有PDF
使用await pdf.setFormFieldValue(fieldName, value)设置每个字段值
使用await pdf.saveAs(outputPath)保存结果

我需要什么先决条件来在Node.js中填写PDF表单？

在运行以下代码示例之前，确认已经准备好三件事：支持的Node.js版本、IronPDF许可证密钥和IronPdfEngine二进制文件。

Node.js版本：IronPDF需要Node.js 18或更高版本。从官方Node.js网站下载当前的LTS版本。该库使用Node.js异步I/O进行所有PDF操作，因此await或Promise链是整个标准模式。不支持旧版本的Node.js，因为该包依赖于需要Node.js 18+的原生ESM和async_hooks功能。

许可证密钥：激活的IronPDF许可证密钥解锁完整的API。开始免费试用以获取开发和测试的密钥，或购买许可证用于生产用途。有关部署选项（环境变量、配置文件、秘密管理器），请参阅使用许可证密钥指南。

IronPdfEngine: Node.js包包括IronPdfEngine，一个跨平台的渲染引擎，用于处理实际的PDF操作。安装和平台特定的说明（Windows、Linux、macOS）请参见使用IronPdfEngine文档。

如何在Node.js代码中设置许可证密钥？

在应用程序启动时应用许可证密钥，在任何PdfDocument调用之前：

const { IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

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

const { IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

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

JavaScript

将密钥存储在环境变量中（如上所示通过process.env.IRONPDF_LICENSE_KEY）可将凭据排除在源代码管理之外。开始指南概述介绍了不同部署环境的其他初始化模式。

如何安装 IronPDF for Node.js?

安装IronPDF for Node.js只需一个npm命令。在您的项目目录中运行它：

//: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

该包附带TypeScript类型声明，因此TypeScript项目无需一个单独的@types包就能获得完整的IntelliSense支持。 Windows、Linux和macOS平台特定的二进制文件在安装期间自动下载。 npm上的@Iron Software/ironpdf包列出了所有发布的版本和对等依赖项。

.d.ts声明意味着IntelliSense在VS Code和其他支持TypeScript语言服务的编辑器中开箱即用。

有关将IronPDF添加到现有monorepo或基于Docker的工作流程的说明，请参见IronPDF for Node.js文档。

如何以编程方式填写 PDF 表单？

加载PDF并将值写入其表单字段需要三个异步调用：saveAs()。下面的示例填写了一个多字段的申请表，并可选择将其平展，以便在交付后无法更改这些值。

完整的表单填写示例是什么样的？

以下示例加载具有多种字段类型的PDF，填写它们并保存结果。欲了解有关创建表单而不是填写表单的集中型内容，请参阅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");

    // 复选框 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");

    // 复选框 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

调用getFormFieldNames()之后，返回的数组会告诉您PDF作者使用的字段名称。这是避免与您没有创建的表单集成时键入错误的最快方法。

提示: 在开发期间调用getFormFieldNames()一次以打印PDF中的准确字段名称。硬编码错误名称是setFormFieldValue()后字段显示为空的最常见原因。

如何处理不同的表单字段类型？

IronPDF支持标准AcroForm字段类型：文本框、复选框、单选按钮、下拉菜单、列表框和签名字段。 setFormFieldValue()方法接受所有类型的字符串值；对于复选框和单选框，接受的值取决于PDF中特定字段定义。

下表显示了每种字段类型的值格式：

PDF AcroForm字段类型及其接受的值格式
字段类型	值格式	范例
文本/多行	任何字符串	"Jane Doe"
复选框	"true"或`"false"`	"true"
单选按钮	选项的导出值	`"女性"`
下拉菜单（组合）	选项的显示文本	`"美国"`
列表框（多选）	字符串数组	`["选项1", "选项2"]`
日期 / 数字	字符串表示	"2024-06-15"

复选框和单选按钮如何工作？

复选框接受"false"取消勾选。单选按钮接受选项的导出值进行选择——导出的字符串通常在PDF的字段属性中可见，并且与显示标签不同。

//: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");

    // 复选框
    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");

    // 复选框
    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

多选列表框字段遵循相同的模式。当一个字段允许多重选择时，传递一个字符串数组，而不是单一值。签名字段可以接收一个代表签名字形的base64编码图像字符串。

getFormFieldNames()列出文档中的实际名称。

填充后如何扁平化PDF表单字段？

扁平化PDF表单将所有字段值合并到静态页面内容中，移除交互层。生成的文档不能再进一步编辑，从而防止在分发过程中意外更改，并确保在所有PDF查看器中一致呈现。

在设置所有字段值后调用flattenAllFormFields()，在保存之前。

//: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

对于最终交付非常适合的情况——签署后的合同、发行后的证明书或批准后的发票。对于需要进一步审查的文件，跳过flattenAllFormFields()并直接保存。

警告: 扁平化对已保存的副本是不可逆的。如果需要重新生成文档，请保留原始未填充的PDF作为模板。)]}

PDF表单自动化的常见用例是什么？

自动化表单填写从高容量文档工作流中移除手动数据输入。以下场景涵盖开发人员使用IronPDF进行的最常见模式。

应用处理：从数据库或REST API中提取申请人数据，并填充用于金融服务、保险或政府接受工作流程的PDF表单。使用合并PDF示例将填充的表单结合起来，以生成单一的多页提交包。

发票和收据生成：用行项目数据、客户详情和计算总计填充发票模板。使用HTML页眉和页脚示例中所示技术添加页眉和页脚。

证书和凭证生成：用收件人姓名、完成日期和课程标题个性化证书模板。使用数字签名示例添加安全性，以防止发行后篡改。在受监管行业中，PDF/A标准通常要求进行长期归档。

报告生成：用分析数据或调查结果填充报告模板。对于需要从头构建PDF布局而不是填充现有表单的情况，请参见HTML到PDF教程。

PDF表单填写在Node.js中的下一步是什么？

本指南演示了加载PDF、填写文本字段、复选框、下拉菜单和单选按钮，将表单扁平化以锁定值，并保存完成的文档。相同的PdfDocument实例支持进一步操作——添加数字签名、压缩输出或提取文本——不需要重新加载文件。

开始免费试用以在您的项目中测试IronPDF，或者查看许可选项以找到适合您部署的计划。

准备好看看您还能做些什么吗？在此查看完整的Node.js教程集合：Node.js中的HTML到PDF

常见问题解答

在 Node.js 中填写 PDF 表单需要哪些先决条件？

您需要Node.js 18或更高版本、IronPDF许可证密钥（提供免费试用），以及IronPdfEngine二进制文件。引擎与@ironsoftware/ironpdf包捆绑，在安装时自动下载。

如何安装 IronPDF for Node.js？

在项目目录中运行npm install @ironsoftware/ironpdf。该命令将安装该包及其适用于Windows、Linux和macOS的平台特定二进制文件。TypeScript类型声明已包含在内。

如何发现PDF表单中的字段名？

在使用PdfDocument.fromFile()加载PDF后，调用await pdf.getFormFieldNames()。该方法返回文档中所有字段名称字符串的数组。PDF字段名区分大小写，因此请使用返回的确切字符串。

复选框和单选按钮接受什么值格式？

复选框接受字符串"true"和"false"以选中和未选中。单选按钮接受目标选项的导出值字符串。使用getFormFieldNames()并检查PDF字段属性以找出正确的导出值。

如何防止填写完的PDF表单被编辑？

在设置所有字段值并在saveAs()之前，调用await pdf.flattenAllFormFields()。展平操作将字段值合并为静态页面内容，并移除交互式表单层。此操作在保存的文件上不可逆。

我可以在Node.js中将IronPDF与TypeScript一起使用吗？

可以。@ironsoftware/ironpdf包内含有TypeScript声明（.d.ts文件），因此您可以在VS Code和其他编辑器中进行完整类型检查和IntelliSense，而无需安装单独的类型包。

How can IronPDF be used for automated PDF form filling?

IronPDF can automate form filling by integrating with databases or APIs to populate PDFs with user data in workflows such as application processing, invoice generation, and certificate issuance.

What is the benefit of storing the IronPDF license key in an environment variable?

Storing the IronPDF license key in an environment variable helps to keep your credentials secure and out of source control, thus enhancing application security.

Can IronPDF handle multi-line text fields in PDF forms?

Yes, IronPDF can handle multi-line text fields by passing the desired text string to the `setFormFieldValue()` method. This is useful for extensive input like comments or descriptions.

What should I do if form fields appear empty after using IronPDF?

If form fields appear empty after using IronPDF, ensure the field names match exactly. Field names are case-sensitive, so use `pdf.getFormFieldNames()` to list and verify the actual field names.

Curtis Chau

立即与工程团队聊天

技术作家

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位，专注于前端开发，精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面，喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

...

开始免费 30 天试用

如何在Node.js中填写PDF表单字段

最小工作流程（5 个步骤）

我需要什么先决条件来在Node.js中填写PDF表单？

如何在Node.js代码中设置许可证密钥？

如何安装 IronPDF for Node.js?

如何以编程方式填写 PDF 表单？

完整的表单填写示例是什么样的？

如何处理不同的表单字段类型？

复选框和单选按钮如何工作？

填充后如何扁平化PDF表单字段？

PDF表单自动化的常见用例是什么？

PDF表单填写在Node.js中的下一步是什么？

常见问题解答

在 Node.js 中填写 PDF 表单需要哪些先决条件？

如何安装 IronPDF for Node.js？

如何发现PDF表单中的字段名？

复选框和单选按钮接受什么值格式？

如何防止填写完的PDF表单被编辑？

我可以在Node.js中将IronPDF与TypeScript一起使用吗？

How can IronPDF be used for automated PDF form filling?

What is the benefit of storing the IronPDF license key in an environment variable?

Can IronPDF handle multi-line text fields in PDF forms?

What should I do if form fields appear empty after using IronPDF?

产品链接