1. IronPDF
  2. 操作指南
  3. 填寫 PDF 表單

如何在 Node.js 中填寫 PDF 表單欄位

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

透過 Node.js 以程式化方式填寫 PDF 表單，可讓您自動化文件工作流程：從使用資料庫記錄填寫申請表單，到大規模生成個人化證書。 IronPDF for Node.js 提供直觀的 API，讓您無需離開 JavaScript 環境，即可載入現有 PDF 檔案、在表單欄位中填入數值，並儲存已填妥的文件。

本指南涵蓋完整的操作流程：安裝套件、套用授權金鑰、填寫文字欄位、核取方塊、下拉式選單及單選按鈕、將表單欄位扁平化以鎖定數值，以及儲存輸出結果。 所有程式碼範例均使用 await 以及 @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
//: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

簡化工作流程（5 個步驟）

1. 安裝 IronPDF：`npm install @ironsoftware/ironpdf` 2. 透過 `IronPdfGlobalConfig.getConfig().licenseKey` 設定您的授權金鑰 3. 載入現有的 PDF 檔案 `PdfDocument.fromFile(path)` 4. 將每個欄位值設定為 `await pdf.setFormFieldValue(fieldName, value)` 5. 將結果儲存為 `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，因其依賴原生 ESM 及 async_hooks 功能，這些功能需 Node.js 18 以上版本方能運作。

授權金鑰：有效的 IronPDF 授權金鑰可解鎖完整的 API 功能。 立即開始免費試用以取得開發與測試授權金鑰，或購買授權用於正式生產環境。 有關部署選項（環境變數、設定檔、機密管理工具），請參閱《使用授權金鑰指南》。

IronPdfEngine：此 Node.js 套件包含 IronPdfEngine，這是一個負責實際 PDF 處理的跨平台渲染引擎。 有關設定及平台特定注意事項（Windows、Linux、macOS），請參閱《使用 IronPdfEngine》文件。

如何在 Node.js 程式碼中設定授權金鑰？

請在應用程式啟動時，於任何 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

將金鑰儲存於環境變數中（如上文 process.env.IRONPDF_LICENSE_KEY 所示），可避免憑證進入版本控制系統。 "入門概覽"涵蓋了適用於不同部署環境的額外初始化模式。

如何安裝適用於 Node.js 的 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 套件列出了所有已發布版本及同級依賴項。

請注意對於 TypeScript 專案，內建的 .d.ts 宣告表示 IntelliSense 可在 VS Code 及其他支援 TypeScript 語言服務的編輯器中立即使用。

有關如何將 IronPDF 整合至現有單一儲存庫 (monorepo) 或基於 Docker 的工作流程，請參閱 IronPDF for Node.js 文件。

如何透過程式碼填寫 PDF 表單？

載入 PDF 並將值寫入其表單欄位需要三個非同步呼叫：setFormFieldValue() 以及 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"
單選按鈕選項的匯出值"女性"
下拉式選單 (Combo)選項的顯示文字"美國"
清單方塊（多選）字串陣列["選項1", "選項2"]
日期 / 數字字串表示法"2024-06-15"

複選框和單選按鈕是如何運作的？

複選框接受 "true" 來勾選，以及 "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 編碼圖像字串。

重要事項若 setFormFieldValue() 似乎無法變更欄位的值，請確認欄位名稱是否完全相符——PDF 欄位名稱區分大小寫。請使用 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 教學。

Node.js 中的 PDF 表單填寫技術下一步該怎麼做？

本指南示範了載入 PDF、填寫文字欄位、核取方塊、下拉式選單及單選按鈕、將表單扁平化以鎖定數值，以及儲存已填妥的文件。 同一個 PdfDocument 實例可支援進一步的操作——例如添加數位簽章、壓縮輸出或擷取文字——而無需重新載入檔案。

立即開始免費試用，在您的專案中測試 IronPDF，或查看授權方案以尋找最適合您部署需求的方案。

準備好探索更多可能性了嗎？ 點此查看完整的 Node.js 教學系列：Node.js 中的 HTML 轉 PDF

常見問題

在 Node.js 中填寫 PDF 表單需要哪些先決條件？

您需要 Node.js 18 或更高版本、IronPDF 授權金鑰（提供免費試用版）以及 IronPdfEngine 二進位檔。該引擎已內建於 @ironsoftware/ironpdf 套件中，並會在安裝過程中自動下載。

如何安裝適用於 Node.js 的 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 中搭配 TypeScript 使用 IronPDF for Node.js 嗎？

是的。@ironsoftware/IronPDF 套件內含 TypeScript 宣告檔（.d.ts 檔案），因此您無需安裝額外的類型套件，即可在 VS Code 及其他編輯器中獲得完整的類型檢查與 IntelliSense 功能。

Curtis Chau
Curtis Chau
  立即與工程團隊聯繫
技術撰稿人

Curtis Chau 擁有卡爾頓大學（Carleton University）的電腦科學學士學位，專精於前端開發，並精通 Node.js、TypeScript、JavaScript 及 React。他熱衷於打造直觀且美觀的用戶介面，喜歡運用現代框架，並創建結構完善、視覺上吸引人的手冊。

除了開發工作之外，Curtis 對物聯網（IoT）抱有濃厚興趣，致力於探索整合硬體與軟體的創新方法。閒暇時，他喜歡玩遊戲和開發 Discord 機器人，將對科技的熱愛與創意相結合。

準備開始了嗎？
版本： 2026.5 just released
Still Scrolling Icon

還在捲動嗎？

想要快速證明？
執行範例 觀看您的 HTML 變成 PDF。