Form API¶

namespace NextPDF\Core\Form;

final class FormFieldManager

/**
 * 新增文字輸入欄位。
 *
 * @param TextField $field  欄位設定
 * @param Rectangle $bounds 欄位在頁面上的位置與尺寸
 * @param Page|null $page   目標頁面（null = 當前頁面）
 */
public function addTextField(
    TextField $field,
    Rectangle $bounds,
    ?Page     $page = null,
): FieldAnnotation

public function addCheckbox(
    CheckboxField $field,
    Rectangle     $bounds,
    ?Page         $page = null,
): FieldAnnotation

public function addRadioGroup(
    RadioGroup $group,
    array      $positions,  // list<Rectangle>，每個選項的位置
    ?Page      $page = null,
): array  // list<FieldAnnotation>

public function addComboBox(
    ComboBoxField $field,
    Rectangle     $bounds,
    ?Page         $page = null,
): FieldAnnotation

public function addListBox(
    ListBoxField  $field,
    Rectangle     $bounds,
    ?Page         $page = null,
): FieldAnnotation

public function addSignatureField(
    SignatureField $field,
    Rectangle      $bounds,
    ?Page          $page = null,
): FieldAnnotation

public function addPushButton(
    PushButtonField $field,
    Rectangle       $bounds,
    ?Page           $page = null,
): FieldAnnotation

/** 取得所有欄位 */
public function allFields(): list<FieldAnnotation>

/**
 * 壓平表單（將填入值燒入為靜態內容）。
 *
 * @param array<string, mixed> $values 欄位名稱 => 值的映射
 */
public function flatten(array $values = []): FlattenResult

/**
 * 設定欄位值（不壓平，保持互動性）。
 *
 * @param array<string, mixed> $values
 */
public function fill(array $values): void

/** 匯出當前表單資料（AcroForm 格式）*/
public function export(): array<string, mixed>

namespace NextPDF\Core\Form\Fields;

final class TextField
{
    public static function create(
        string             $name,
        string             $label       = '',
        string             $placeholder = '',
        bool               $required    = false,
        bool               $multiline   = false,
        ?int               $maxLength   = null,
        string             $tooltip     = '',
        string             $ariaLabel   = '',
    ): self

    public function withAppearance(FieldAppearance $appearance): self
    public function withDefaultValue(string $value): self
    public function withReadOnly(bool $readonly): self
}

final class CheckboxField
{
    public static function create(
        string $name,
        string $label      = '',
        bool   $checked    = false,
        bool   $required   = false,
        string $onValue    = 'Yes',
        string $tooltip    = '',
    ): self

    public function withAppearance(FieldAppearance $appearance): self
}

final class RadioGroup
{
    public static function create(
        string $name,
        array  $options,   // list<RadioOption>
        string $selected   = '',
        bool   $required   = false,
    ): self
}

final class RadioOption
{
    public static function create(
        string $value,
        string $label,
    ): self
}

final class ComboBoxField
{
    /**
     * @param array<string, string> $options 值 => 顯示標籤
     */
    public static function create(
        string $name,
        string $label    = '',
        array  $options  = [],
        string $selected = '',
        bool   $editable = false,
        bool   $required = false,
    ): self

    public function withAppearance(FieldAppearance $appearance): self
}

final class SignatureField
{
    public static function create(
        string $name,
        string $label = '',
    ): self
}

namespace NextPDF\Core\Form\ValueObjects;

final class FieldAppearance
{
    public static function create(): self

    public function withBackgroundColor(string $hex): self
    public function withBorderColor(string $hex): self
    public function withBorderWidth(float $pt): self
    public function withFontName(string $name): self
    public function withFontSize(float $pt): self
    public function withTextColor(string $hex): self
    public function withTextAlignment(string $alignment): self  // 'left'|'center'|'right'
}

namespace NextPDF\Core\Form;

final readonly class FlattenResult
{
    /** 壓平後的 Document（可繼續進行其他操作）*/
    public function document(): Document

    /** 成功壓平的欄位數量 */
    public function flattenedCount(): int

    /** 未找到對應值的欄位名稱列表 */
    public function missingFields(): list<string>

    /** 忽略的未知欄位名稱列表 */
    public function unknownFields(): list<string>
}