Node.js에서 PDF 양식 필드를 채우는 방법

Node.js에서 PDF 양식을 채우기 위해 어떤 필수 조건이 필요한가요?

아래 코드 예제를 실행하기 전에 세 가지를 확인하세요: 지원되는 Node.js 버전, IronPDF 라이선스 키, IronPdfEngine 바이너리.

Node.js 버전: IronPDF는 Node.js 18 이상을 필요로 합니다. 현재 LTS 릴리스를 공식 Node.js 웹사이트에서 다운로드하세요. 라이브러리는 모든 PDF 작업에 대해 Node.js 비동기 I/O를 사용하므로, await 또는 Promise 체인이 전반적인 표준 패턴입니다. Node.js의 오래된 버전은 패키지가 Node.js 18 이상의 기본 ESM 및 async_hooks 기능에 의존하기 때문에 지원되지 않습니다.

라이선스 키: 활성화된 IronPDF 라이선스 키는 전체 API를 해제합니다. 무료 체험을 시작해서 개발 및 테스트용 키를 얻거나, 생산 사용을 위한 라이선스 구매를 할 수 있습니다. 배포 옵션(환경 변수, 구성 파일, 비밀 관리자)은 라이선스 키 사용 가이드를 참조하세요.

IronPdfEngine: Node.js 패키지에 포함된 @@IronPdfEngine, 모든 실제 PDF 조작을 처리하는 크로스 플랫폼 렌더링 엔진. 설정 및 플랫폼별 주의 사항(Windows, Linux, macOS)은 IronPdfEngine 사용 문서에 나와 있습니다.

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

Node.js 용 IronPDF 어떻게 설치하나요?

Node.js를 위한 IronPDF 설치는 단일 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

패키지는 TypeScript 타입 선언과 함께 제공되므로, 별도의 @types 패키지 없이도 TypeScript 프로젝트는 완전한 IntelliSense 지원을 받을 수 있습니다. Windows, Linux 및 macOS에 대한 플랫폼별 바이너리는 설치 중 자동으로 다운로드됩니다. npm의 @Iron Software/ironpdf 패키지는 모든 게시된 버전 및 동료 패키지를 나열합니다.

TypeScript 프로젝트의 경우, 포함된 .d.ts 선언은 VS Code 및 TypeScript 언어 서비스를 지원하는 다른 편집기에서 상자 밖에서 제대로 작동하는 IntelliSense를 의미합니다.

기존 모노레포 또는 Docker 기반 워크플로우에 IronPDF를 추가하는 방법에 대한 지침은 Node.js를 위한 IronPDF 문서를 참조하세요.

PDF 양식을 프로그램으로 자동으로 채우는 방법은 무엇인가요?

PDF를 로드하고 그 폼 필드에 값들을 쓰려면 세 가지 비동기 호출이 필요합니다: PdfDocument.fromFile(), 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입니다. PDF 파일을 빠르고 효율적으로 조작할 수 있습니다. 또한 PDF/A 형식으로 내보내기 및 PDF 문서의 디지털 서명과 같은 많은 유용한 기능을 가지고 있습니다.

Milan Jovanovic

마이크로소프트 MVP

사례 연구 보기

IronOCR 덕분에 연간 $40,000를 수동 프로세싱에서 절약하고 생산성을 높이며 고부가가치 작업에 자원을 활용할 수 있습니다. 강력히 추천합니다.

브렌트 마첼

최고 기술 책임자, OPYN

사례 연구 보기

IronSuite는 우리의 운영에서 중요한 역할을 합니다. 이것들은 사업 전반에 걸쳐 효율성을 높이는 도구로, 평면도 생성 및 재고 관리 개선을 포함합니다.

데이비드 존스

리드 소프트웨어 엔지니어, Agorus Build

사례 연구 보기

다른 양식 필드 유형을 어떻게 처리하나요?

IronPDF는 표준 AcroForm 필드 유형을 지원합니다: 텍스트 상자, 체크박스, 라디오 버튼, 드롭다운, 목록 상자 및 서명 필드. setFormFieldValue() 메서드는 모든 유형에 대해 문자열 값을 수용하며, 체크박스 및 라디오 필드의 경우, 허용된 값은 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);

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);

평면화는 최종 전달에 적합합니다 — 서명 후 계약서, 발행 후 증명서, 승인 후 송장 등. 최종 결정 전에 추가 검토가 필요한 문서는 flattenAllFormFields()을 건너뛰고 저장하세요.

PDF 양식 자동화의 일반적인 사용 사례는 무엇입니까?

자동 양식 작성은 대량 문서 워크플로에서 수작업 데이터 입력을 제거합니다. 다음 시나리오는 개발자가 IronPDF로 구현하는 가장 빈번한 패턴을 다룹니다.

신청서 처리: 신청자 데이터를 데이터베이스 또는 REST API에서 가져와 금융 서비스, 보험 또는 정부 접수 워크플로의 PDF 양식을 채웁니다. 기입된 양식을 PDF 병합 예제를 사용하여 하나의 다중 페이지 제출 패킷을 생성합니다.

송장 및 영수증 생성: 항목 데이터, 고객 정보 및 계산된 총액으로 송장 템플릿을 채웁니다. HTML 헤더 및 푸터 예제에서 보여준 기법을 사용하여 페이지 헤더와 푸터를 추가하세요.

인증서 및 자격 증명 생성: 수령인 이름, 완료 날짜 및 과정 제목으로 인증서 템플릿을 개인화합니다. 발행 후 변조를 방지하기 위한 디지털 서명 예제를 사용하여 보안을 추가합니다. PDF/A 표준은 규제된 산업에서 인증서를 장기 보관에 일반적으로 요구됩니다.

보고서 생성: 분석 데이터나 설문 결과로 보고서 템플릿을 채웁니다. 기존 양식을 채우기보다는 처음부터 PDF 레이아웃을 구축해야 하는 경우 HTML to PDF 튜토리얼을 참조하세요.

Node.js에서 PDF 양식 작성을 위한 다음 단계는 무엇입니까?

이 가이드에서는 PDF를 로드하고 텍스트 필드, 체크박스, 드롭다운 및 라디오 버튼을 채우고, 값을 고정하여 양식을 평면화하고 완료된 문서를 저장하는 방법을 설명했습니다. 같은 PdfDocument 인스턴스는 추가 작업 — 디지털 서명 추가, 출력 압축, 텍스트 추출 —을 지원하며 파일을 다시 로드할 필요가 없습니다.

무료 체험을 시작하세요 프로젝트에서 IronPDF를 테스트하거나 라이선싱 옵션 보기에서 배포에 맞는 계획을 찾습니다.

당신이 할 수 있는 다른 일들을 알아볼 준비가 되셨나요? Node.js 튜토리얼 전체 컬렉션은 여기에서 확인하세요: Node.js의 HTML to PDF