Node.js에서 PDF 양식 필드를 채우는 방법
Node.js에서 PDF 양식을 프로그래밍 방식으로 채우면 데이터베이스 레코드를 사용한 애플리케이션 양식 채우기에서 대량의 개인화된 인증서 생성에 이르기까지 문서 워크플로우를 자동화할 수 있습니다. IronPDF for Node.js는 기존 PDF를 로드하고, 양식 필드에 값을 쓰고, JavaScript 환경을 벗어나지 않고 완성된 문서를 저장할 수 있는 간단한 API를 제공합니다.
이 가이드는 Install-Package, 라이선스 키 적용, 텍스트 필드, 체크박스, 드롭다운 및 라디오 버튼 채우기, 값을 잠그기 위해 양식 필드를 평면화, 출력 저장 등 전체 워크플로우를 다룹니다. 모든 코드 예제에는 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//: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");
})();최소 워크플로우(5단계)
1. IronPDF 설치: `npm install @ironsoftware/ironpdf` 2. `IronPdfGlobalConfig.getConfig().licenseKey`을 통해 라이선스 키를 설정하십시오. 3. `PdfDocument.fromFile(path)`을 사용하여 기존 PDF를 불러옵니다. 4. 각 필드 값을 `await pdf.setFormFieldValue(fieldName, value)`로 설정하십시오. 5. 결과를 `await pdf.saveAs(outputPath)`로 저장하세요.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 18 이상이 필요한 네이티브 ESM 및 async_hooks 기능을 사용하므로, 이전 버전의 Node.js는 지원되지 않습니다.
라이선스 키: 활성화된 IronPDF 라이선스 키는 전체 API를 해제합니다. 무료 체험을 시작해서 개발 및 테스트용 키를 얻거나, 생산 사용을 위한 라이선스 구매를 할 수 있습니다. 배포 옵션(환경 변수, 구성 파일, 비밀 관리자)은 라이선스 키 사용 가이드를 참조하세요.
IronPdfEngine: 이 Node.js 패키지에는 실제 PDF 조작을 처리하는 크로스 플랫폼 렌더링 엔진인 IronPdfEngine가 포함되어 있습니다. 설정 및 플랫폼별 주의 사항(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;키를 환경 변수에 저장하면(위에서 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 패키지는 모든 게시된 버전 및 동료 패키지를 나열합니다.
.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);getFormFieldNames()를 호출한 후 반환된 배열을 통해 PDF 작성자가 사용한 필드 이름을 확인할 수 있습니다. 자신이 만들지 않은 양식과 통합할 때는 필드 이름에서 철자를 피하기 위한 가장 빠른 방법입니다.
getFormFieldNames()를 한 번 호출하면 PDF에 정확한 필드 이름이 PRINT됩니다. 잘못된 이름을 하드코딩하는 것은 setFormFieldValue().다른 양식 필드 유형을 어떻게 처리하나요?
IronPDF는 표준 AcroForm 필드 유형을 지원합니다: 텍스트 상자, 체크박스, 라디오 버튼, 드롭다운, 목록 상자 및 서명 필드. setFormFieldValue() 메서드는 모든 유형에 대해 문자열 값을 허용합니다. 체크박스 및 라디오 버튼 필드의 경우, 허용되는 값은 PDF 내의 특정 필드 정의에 따라 다릅니다.
아래 테이블은 각 필드 유형에 맞는 값 형식을 보여줍니다:
| 필드 유형 | 값 형식 | 예 |
|---|---|---|
| 텍스트 / 멀티라인 | 아무 문자열 | "Jane Doe" |
| 체크박스 | "true" 또는 "false" | "true" |
| 라디오 버튼 | 옵션의 내보내기 값 | "여성" |
| 드롭다운 (콤보) | 옵션의 표시 텍스트 | "미국" |
| 리스트 박스 (멀티 선택) | 문자열 배열 | ["Option1", "Option2"] |
| 날짜 / 숫자 | 문자열 표현 | "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);멀티 선택 리스트 박스 필드는 동일한 패턴을 따릅니다. 여러 선택을 허용하는 필드에는 단일 값 대신 문자열 배열을 전달합니다. 서명 필드는 서명 그래픽을 나타내는 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);평면화는 최종 전달에 적합합니다 — 서명 후 계약서, 발행 후 증명서, 승인 후 송장 등. 최종 확정 전에 추가 검토가 필요한 문서의 경우, 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
자주 묻는 질문
Node.js를 사용하여 PDF 양식을 작성하려면 어떤 사전 준비가 필요합니까?
Node.js 18 이상, IronPDF 라이선스 키(무료 체험 가능), 그리고 IronPdfEngine 바이너리가 필요합니다. 이 엔진은 @ironsoftware/ironpdf 패키지에 번들로 포함되어 있으며 설치 시 자동으로 다운로드됩니다.
Node.js용 IronPDF를 어떻게 설치하나요?
npm install @ironsoftware/ironpdf를 프로젝트 디렉터리에서 실행합니다. 이 명령은 Windows, Linux, 및 macOS에 대한 패키지와 플랫폼별 바이너리를 설치합니다. TypeScript 타입 선언도 포함되어 있습니다.
PDF 양식에서 필드 이름을 어떻게 찾나요?
PDF를 PdfDocument.fromFile()로 로드한 후 await pdf.getFormFieldNames()를 호출하십시오. 이 메서드는 문서 내 모든 필드 이름 문자열의 배열을 반환합니다. PDF 필드 이름은 대소문자를 구분하므로 반환된 정확한 문자열을 사용하세요.
체크박스와 라디오 버튼은 어떤 값 형식을 수용하나요?
체크박스는 체크를 위해 "true" 문자열을, 체크 해제를 위해 "false" 문자열을 수락합니다. 라디오 버튼은 대상 옵션의 내보내기 값을 문자열로 수락합니다. getFormFieldNames()를 사용하고 PDF 필드 속성을 검사하여 올바른 내보내기 값을 찾으세요.
채워진 PDF 양식이 수정되지 않도록 하려면 어떻게 해야 하나요?
saveAs() 전에 모든 필드 값을 설정한 후 await pdf.flattenAllFormFields()를 호출하세요. 평면화는 필드 값을 정적 페이지 콘텐츠에 병합하고 대화형 양식 레이어를 제거합니다. 이 작업은 저장된 파일에서 되돌릴 수 없습니다.
IronPDF for Node.js를 TypeScript와 함께 사용할 수 있나요?
네. @ironsoftware/ironpdf 패키지는 TypeScript 선언(.d.ts 파일)을 함께 제공하므로, 별도의 types 패키지를 설치하지 않고도 VS Code 및 다른 편집기에서 전체 타입 검사와 IntelliSense를 사용할 수 있습니다.
아직도 스크롤하고 계신가요?
빠른 증거를 원하시나요?
샘플을 실행하세요 HTML이 PDF로 변환되는 것을 지켜보세요.
무료로 시작하세요
무료로 시작하세요
무료 라이브 데모 예약하기
신용카드나 계정 생성은 필요하지 않습니다.
