양식 필드 생성

PDF 문서에 대화형 양식 필드를 추가합니다. PDF Oxide는 표준 AcroForm 위젯 유형을 모두 지원합니다. 텍스트 필드, 체크박스, 라디오 버튼 그룹, 콤보 박스(드롭다운), 리스트 박스, 푸시 버튼이 그것입니다.

바인딩 지원 범위(v0.3.38). FluentPageBuilder는 Rust, Python, Node/TypeScript, C#, Go, WASM에서 text_field, checkbox, combo_box, radio_group, push_button을 제공합니다(DocumentBuilder → AcroForm 위젯 참조). 이 페이지에서 다루는 Rust 전용 저수준 메서드 PdfWriter::text_field / checkbox 등은 위젯별 추가 옵션(여러 줄 텍스트, 비밀번호 필드, 리스트 박스, 테두리 색상)을 제공하므로, AcroForm을 세밀하게 제어해야 할 때 사용하세요. 기존 양식의 입력과 **평탄화(flattening)**는 모든 바인딩에서 동작합니다. 양식 필드 편집과 PDF 양식 채우기를 참조하세요.

빠른 예제

Rust

use pdf_oxide::writer::{PdfWriter, TextFieldWidget, CheckboxWidget};
use pdf_oxide::geometry::Rect;

let mut writer = PdfWriter::new();
{
    let mut page = writer.add_letter_page();
    page.add_text("Name:", 72.0, 720.0, "Helvetica", 12.0);
    page.text_field("name", Rect::new(130.0, 716.0, 200.0, 20.0));
    page.add_text("I agree to terms:", 72.0, 690.0, "Helvetica", 12.0);
    page.checkbox("agree", Rect::new(200.0, 686.0, 15.0, 15.0));
    page.finish();
}
writer.save("form.pdf")?;

Python

from pdf_oxide import DocumentBuilder

(DocumentBuilder()
    .letter_page()
        .at(72, 720).text("Name:")
        .text_field("name", 130, 716, 200, 20)
        .at(72, 690).text("I agree to terms:")
        .checkbox("agree", 200, 686, 15, 15, False)
    .done()
    .save("form.pdf"))

Node / TypeScript

import { DocumentBuilder } from "pdf-oxide";

await new DocumentBuilder()
  .letterPage()
    .at(72, 720).text("Name:")
    .textField("name", 130, 716, 200, 20)
    .at(72, 690).text("I agree to terms:")
    .checkbox("agree", 200, 686, 15, 15, false)
  .done()
  .save("form.pdf");

C#

DocumentBuilder.Create()
    .LetterPage()
        .At(72, 720).Text("Name:")
        .TextField("name", 130, 716, 200, 20)
        .At(72, 690).Text("I agree to terms:")
        .Checkbox("agree", 200, 686, 15, 15, false)
    .Done()
    .Save("form.pdf");

Go

builder := pdfoxide.NewDocumentBuilder()
builder.LetterPage().
    At(72, 720).Text("Name:").
    TextField("name", 130, 716, 200, 20, "").
    At(72, 690).Text("I agree to terms:").
    Checkbox("agree", 200, 686, 15, 15, false).
    Done()
_ = builder.Save("form.pdf")

C++

#include <pdf_oxide/pdf_oxide.hpp>

auto builder = pdf_oxide::DocumentBuilder::create();
auto page = builder.letter_page();
page.at(72, 720).text("Name:")
    .text_field("name", 130, 716, 200, 20)
    .at(72, 690).text("I agree to terms:")
    .checkbox("agree", 200, 686, 15, 15, false);
page.done();
builder.save("form.pdf");

Swift

import PdfOxide

let builder = try DocumentBuilder.create()
let page = try builder.letterPage()
try page.at(72, 720); try page.text("Name:")
try page.textField("name", 130, 716, 200, 20)
try page.at(72, 690); try page.text("I agree to terms:")
try page.checkbox("agree", 200, 686, 15, 15, checked: false)
try page.done()
try builder.save("form.pdf")

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

final builder = DocumentBuilder.create();
builder.letterPage()
    .at(72, 720).text("Name:")
    .textField("name", 130, 716, 200, 20)
    .at(72, 690).text("I agree to terms:")
    .checkbox("agree", 200, 686, 15, 15, false)
    .done();
builder.save("form.pdf");

R

library(pdfoxide)

builder <- pdf_builder_create()
page <- pdf_builder_letter_page(builder)
pdf_page_at(page, 72, 720); pdf_page_builder_text(page, "Name:")
pdf_page_text_field(page, "name", 130, 716, 200, 20)
pdf_page_at(page, 72, 690); pdf_page_builder_text(page, "I agree to terms:")
pdf_page_checkbox(page, "agree", 200, 686, 15, 15, checked = FALSE)
pdf_page_done(page)
pdf_builder_save(builder, "form.pdf")

Julia

using PdfOxide

builder = DocumentBuilder()
page = letter_page(builder)
at(page, 72, 720); text(page, "Name:")
text_field(page, "name", 130, 716, 200, 20)
at(page, 72, 690); text(page, "I agree to terms:")
checkbox(page, "agree", 200, 686, 15, 15, false)
done(page)
save(builder, "form.pdf")

Zig

const pdf_oxide = @import("pdf_oxide");

var builder = try pdf_oxide.DocumentBuilder.create();
defer builder.deinit();
var page = try builder.letterPage();
try page.at(72, 720);
try page.text("Name:");
try page.textField("name", 130, 716, 200, 20, null);
try page.at(72, 690);
try page.text("I agree to terms:");
try page.checkbox("agree", 200, 686, 15, 15, false);
try page.done();
try builder.save("form.pdf");

Objective-C

#import "POXPdfOxide.h"
NSError *err = nil;

POXDocumentBuilder *builder = [POXDocumentBuilder createWithError:&err];
POXPageBuilder *page = [builder letterPageWithError:&err];
[page at:72 y:720 error:&err]; [page text:@"Name:" error:&err];
[page textFieldName:@"name" x:130 y:716 w:200 h:20 defaultValue:nil error:&err];
[page at:72 y:690 error:&err]; [page text:@"I agree to terms:" error:&err];
[page checkboxName:@"agree" x:200 y:686 w:15 h:15 checked:NO error:&err];
[page done:&err];
[builder saveToPath:@"form.pdf" error:&err];

Elixir

{:ok, builder} = PdfOxide.builder()
{:ok, page} = PdfOxide.builder_letter_page(builder)
PdfOxide.page_at(page, 72, 720); PdfOxide.page_text(page, "Name:")
PdfOxide.page_text_field(page, "name", 130, 716, 200, 20)
PdfOxide.page_at(page, 72, 690); PdfOxide.page_text(page, "I agree to terms:")
PdfOxide.page_checkbox(page, "agree", 200, 686, 15, 15, false)
PdfOxide.page_done(page)
PdfOxide.builder_save(builder, "form.pdf")

위젯 유형

TextFieldWidget — 텍스트 입력

한 줄 또는 여러 줄의 텍스트 입력 필드입니다.

use pdf_oxide::writer::TextFieldWidget;
use pdf_oxide::geometry::Rect;

// Basic text field
let field = TextFieldWidget::new("username", Rect::new(72.0, 700.0, 200.0, 20.0));

// Fully configured text field
let field = TextFieldWidget::new("email", Rect::new(72.0, 670.0, 250.0, 20.0))
    .with_value("user@example.com")
    .with_default_value("")
    .with_max_length(100)
    .required()
    .with_tooltip("Enter your email address")
    .with_font("Helv", 12.0)
    .with_text_color(0.0, 0.0, 0.0)
    .with_border_color(0.5, 0.5, 0.5)
    .with_background_color(1.0, 1.0, 0.95);

// Password field (characters are masked)
let password = TextFieldWidget::new("password", Rect::new(72.0, 640.0, 200.0, 20.0))
    .password();

// Multi-line text area
let notes = TextFieldWidget::new("notes", Rect::new(72.0, 550.0, 300.0, 80.0))
    .multiline();

주요 메서드:

메서드	설명
.with_value(s)	현재 텍스트 값을 설정
.with_default_value(s)	초기화 시 사용할 값을 설정
.with_max_length(n)	최대 문자 수
.required()	필수 필드로 표시
.read_only()	편집 금지
.password()	입력 문자를 가림
.multiline()	여러 줄 허용
.with_tooltip(s)	마우스 오버 시 툴팁 텍스트
.with_font(name, size)	글꼴과 크기를 설정
.with_text_color(r, g, b)	텍스트 색상 설정(0.0–1.0 RGB)
.with_border_color(r, g, b)	테두리 색상 설정
.with_background_color(r, g, b)	배경 색상 설정

CheckboxWidget — 체크박스

켜짐/꺼짐 상태를 전환하는 필드입니다.

use pdf_oxide::writer::CheckboxWidget;
use pdf_oxide::geometry::Rect;

// Basic checkbox
let cb = CheckboxWidget::new("agree", Rect::new(72.0, 700.0, 15.0, 15.0));

// Pre-checked checkbox with custom export value
let cb = CheckboxWidget::new("newsletter", Rect::new(72.0, 680.0, 15.0, 15.0))
    .checked()
    .with_export_value("subscribed")
    .with_tooltip("Subscribe to newsletter");

주요 메서드:

메서드	설명
.checked()	초기 상태를 체크됨으로 설정
.with_export_value(s)	양식 제출 시 전송되는 값
.with_tooltip(s)	마우스 오버 시 툴팁 텍스트
.read_only()	전환 금지

RadioButtonGroup — 라디오 버튼

상호 배타적인 선택지 그룹입니다. 그룹 내 모든 버튼은 같은 필드 이름을 공유하며, 하나를 선택하면 나머지는 선택 해제됩니다.

use pdf_oxide::writer::RadioButtonGroup;
use pdf_oxide::geometry::Rect;

let group = RadioButtonGroup::new("color")
    .add_button("Red", Rect::new(72.0, 700.0, 15.0, 15.0))
    .add_button("Green", Rect::new(72.0, 680.0, 15.0, 15.0))
    .add_button("Blue", Rect::new(72.0, 660.0, 15.0, 15.0))
    .with_selected("Green");  // Pre-select "Green"

주요 메서드:

메서드	설명
.add_button(value, rect)	라디오 선택지를 추가
.with_selected(value)	선택지를 미리 선택
.no_toggle_off()	모든 선택지의 해제를 금지

ComboBoxWidget — 드롭다운

선택적으로 텍스트를 편집할 수 있는 드롭다운 선택 필드입니다.

use pdf_oxide::writer::ComboBoxWidget;
use pdf_oxide::writer::form_fields::ChoiceOption;
use pdf_oxide::geometry::Rect;

let combo = ComboBoxWidget::new("country", Rect::new(72.0, 700.0, 200.0, 20.0))
    .add_option("US", "United States")
    .add_option("GB", "United Kingdom")
    .add_option("DE", "Germany")
    .add_option("JP", "Japan")
    .with_selected("US");

주요 메서드:

메서드	설명
.add_option(value, label)	선택 가능한 선택지를 추가
.with_selected(value)	선택지를 미리 선택
.editable()	사용자 정의 값 입력을 허용
.sorted()	선택지를 알파벳순으로 정렬

ListBoxWidget — 다중 선택 리스트

단일 또는 다중 선택이 가능한 스크롤 가능한 리스트 필드입니다.

use pdf_oxide::writer::ListBoxWidget;
use pdf_oxide::geometry::Rect;

let list = ListBoxWidget::new("languages", Rect::new(72.0, 600.0, 200.0, 80.0))
    .add_option("rust", "Rust")
    .add_option("python", "Python")
    .add_option("go", "Go")
    .add_option("typescript", "TypeScript")
    .multi_select()
    .with_selected("rust");

주요 메서드:

메서드	설명
.add_option(value, label)	선택 가능한 선택지를 추가
.with_selected(value)	선택지를 미리 선택
.multi_select()	여러 항목 선택을 허용
.sorted()	선택지를 알파벳순으로 정렬

PushButtonWidget — 버튼

동작(제출, 초기화 또는 JavaScript)을 실행하는 클릭 가능한 버튼입니다.

use pdf_oxide::writer::PushButtonWidget;
use pdf_oxide::geometry::Rect;

let submit = PushButtonWidget::new("submit", Rect::new(72.0, 500.0, 100.0, 30.0))
    .with_label("Submit")
    .submit_form("https://example.com/submit");

let reset = PushButtonWidget::new("reset", Rect::new(180.0, 500.0, 100.0, 30.0))
    .with_label("Reset")
    .reset_form();

고급 예제

전체 등록 양식

use pdf_oxide::writer::{
    PdfWriter, PdfWriterConfig,
    TextFieldWidget, CheckboxWidget, RadioButtonGroup,
    ComboBoxWidget, PushButtonWidget,
};
use pdf_oxide::geometry::Rect;

let config = PdfWriterConfig::default()
    .with_title("Registration Form")
    .with_author("HR Department");

let mut writer = PdfWriter::with_config(config);
{
    let mut page = writer.add_letter_page();

    // Title
    page.add_text("Employee Registration Form", 72.0, 740.0, "Helvetica-Bold", 18.0);

    // Personal Information
    page.add_text("First Name:", 72.0, 700.0, "Helvetica", 12.0);
    page.add_text_field(
        TextFieldWidget::new("first_name", Rect::new(170.0, 696.0, 200.0, 20.0))
            .required()
    );

    page.add_text("Last Name:", 72.0, 670.0, "Helvetica", 12.0);
    page.add_text_field(
        TextFieldWidget::new("last_name", Rect::new(170.0, 666.0, 200.0, 20.0))
            .required()
    );

    page.add_text("Email:", 72.0, 640.0, "Helvetica", 12.0);
    page.add_text_field(
        TextFieldWidget::new("email", Rect::new(170.0, 636.0, 250.0, 20.0))
            .required()
            .with_tooltip("Work email address")
    );

    // Department dropdown
    page.add_text("Department:", 72.0, 610.0, "Helvetica", 12.0);
    page.add_combo_box(
        ComboBoxWidget::new("department", Rect::new(170.0, 606.0, 200.0, 20.0))
            .add_option("eng", "Engineering")
            .add_option("sales", "Sales")
            .add_option("hr", "Human Resources")
            .add_option("ops", "Operations")
    );

    // Employment type radio buttons
    page.add_text("Employment Type:", 72.0, 570.0, "Helvetica", 12.0);
    page.add_text("Full-time", 95.0, 550.0, "Helvetica", 10.0);
    page.add_text("Part-time", 95.0, 530.0, "Helvetica", 10.0);
    page.add_text("Contract", 95.0, 510.0, "Helvetica", 10.0);
    page.add_radio_group(
        RadioButtonGroup::new("employment_type")
            .add_button("fulltime", Rect::new(72.0, 548.0, 15.0, 15.0))
            .add_button("parttime", Rect::new(72.0, 528.0, 15.0, 15.0))
            .add_button("contract", Rect::new(72.0, 508.0, 15.0, 15.0))
            .with_selected("fulltime")
    );

    // Agreement checkbox
    page.add_text("I agree to the terms and conditions", 95.0, 470.0, "Helvetica", 10.0);
    page.add_checkbox(
        CheckboxWidget::new("agree_terms", Rect::new(72.0, 468.0, 15.0, 15.0))
            .with_export_value("agreed")
    );

    // Submit button
    page.add_push_button(
        PushButtonWidget::new("submit", Rect::new(72.0, 420.0, 120.0, 30.0))
            .with_label("Submit Form")
    );

    page.finish();
}

writer.save("registration_form.pdf")?;

기존 PDF에 양식 필드 추가

이미 존재하는 PDF 문서에 필드를 추가하려면 DocumentEditor를 사용하세요.

use pdf_oxide::editor::DocumentEditor;
use pdf_oxide::writer::TextFieldWidget;
use pdf_oxide::geometry::Rect;

let mut editor = DocumentEditor::open("template.pdf")?;

let field = TextFieldWidget::new("signature", Rect::new(72.0, 100.0, 250.0, 25.0))
    .with_tooltip("Sign here");

editor.add_form_field(0, field)?;  // Add to page 0
editor.save("signed_template.pdf")?;

관련 페이지

• DocumentBuilder 저수준 API — fluent API로 페이지 구성하기
• 주석 생성 — 비대화형 주석 유형
• PdfBuilder Fluent API — 고수준 PDF 생성