表單欄位

Form 模組（FormFieldManager、FormField）用於在 PDF 中建立互動式 AcroForm 表單欄位。欄位類型由 FormFieldType 列舉定義：TEXT、PASSWORD、TEXTAREA、CHECKBOX、RADIO、LISTBOX、COMBOBOX、BUTTON。所有方法皆回傳 static，支援方法鏈。

快速參考

方法	欄位類型
`textField()`	單行文字輸入
`checkboxField()`	核取方塊
`radioField()`	單選按鈕（群組化）
`listboxField()`	可捲動列表
`comboboxField()`	下拉選單
`buttonField()`	按鈕（可搭配 JavaScript 動作）
`flattenFields()`	將所有互動欄位轉換為靜態內容

FormFieldType 列舉

php

enum FormFieldType: string
{
    case TEXT     = 'text';
    case PASSWORD = 'password';
    case TEXTAREA = 'textarea';
    case CHECKBOX = 'checkbox';
    case RADIO    = 'radio';
    case LISTBOX  = 'listbox';
    case COMBOBOX = 'combobox';
    case BUTTON   = 'button';
}

基本範例

php

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Registration Form', newLine: true)
    ->ln(5)

    // 文字欄位
    ->cell(30, 8, 'Name:')
    ->textField('name', 45, null, 80, 8, [
        'border'    => ['width' => 1],
        'maxLength' => 100,
    ])
    ->ln(12)

    // Email 欄位
    ->cell(30, 8, 'Email:')
    ->textField('email', 45, null, 80, 8)
    ->ln(12)

    // 核取方塊
    ->checkboxField('agree', 15, null, 5, 5)
    ->cell(0, 5, '  I agree to the terms', newLine: true)
    ->ln(10)

    // 下拉選單
    ->cell(30, 8, 'Country:')
    ->comboboxField('country', 45, null, 60, 8, ['US', 'UK', 'TW', 'JP', 'DE'])
    ->ln(12)

    // 提交按鈕
    ->buttonField('submit', 45, null, 40, 10, 'Submit', 'submitForm("https://example.com/submit")');

文字欄位（textField）

php

$pdf->textField(
    string $name,
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    array  $prop = []
);

$y 傳入 null 表示使用目前的垂直游標位置。

php

// 基本文字輸入
$pdf->cell(30, 8, 'Name:')
    ->textField('name', 45, null, 80, 8);

// 帶有最大長度限制與預設值
$pdf->textField('phone', 45, null, 80, 8, [
    'maxLength' => 15,
    'value'     => '+886',
]);

核取方塊（checkboxField）

php

$pdf->checkboxField(
    string $name,
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    bool   $checked = false
);

php

$pdf->checkboxField('newsletter', 15, null, 5, 5, checked: true)
    ->cell(0, 5, '  Subscribe to newsletter', newLine: true)
    ->checkboxField('terms', 15, null, 5, 5)
    ->cell(0, 5, '  I accept the terms and conditions', newLine: true);

單選按鈕（radioField）

php

$pdf->radioField(
    string $name,
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    array  $prop = []
);

使用相同的 $name 建立互斥的單選按鈕群組：

php

$pdf->cell(30, 8, 'Gender:')
    ->radioField('gender', 45, null, 5, 5, ['value' => 'male'])
    ->cell(10, 5, ' M')
    ->radioField('gender', 65, null, 5, 5, ['value' => 'female'])
    ->cell(10, 5, ' F')
    ->radioField('gender', 85, null, 5, 5, ['value' => 'other'])
    ->cell(10, 5, ' Other');

同一群組中只能有一個按鈕被選取。當使用者選取新的選項時，先前的選取會自動取消。

列表與下拉選單（listboxField / comboboxField）

php

$pdf->listboxField(
    string $name,
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    array  $values,
    array  $prop = []
);

$pdf->comboboxField(
    string $name,
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    array  $values,
    array  $prop = []
);

listboxField() 渲染為可捲動的多行列表。comboboxField() 渲染為單行下拉選單。

php

// 下拉選單
$pdf->cell(30, 8, 'Country:')
    ->comboboxField('country', 45, null, 60, 8, ['TW', 'US', 'UK', 'JP', 'DE']);

// 可捲動列表
$pdf->cell(30, 8, 'Skills:')
    ->listboxField('skills', 45, null, 60, 30, [
        'PHP', 'JavaScript', 'Python', 'Go', 'Rust',
    ]);

按鈕（buttonField）

php

$pdf->buttonField(
    string $name,
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    string $caption,
    string $action = ''
);

buttonField() 建立一個按鈕，可搭配 JavaScript 動作字串執行操作：

php

// 重設表單
$pdf->buttonField('reset', 15, null, 40, 10, 'Reset', 'this.resetForm()');

// 列印文件
$pdf->buttonField('print', 60, null, 40, 10, 'Print', 'this.print()');

// 提交表單至伺服器
$pdf->buttonField('submit', 105, null, 40, 10, 'Submit', 'submitForm("https://example.com/submit")');

欄位屬性

$prop 陣列控制欄位的外觀與行為：

鍵	類型	說明
`border`	`array`	邊框樣式，包含 `width`、`color`、`style`
`bgcolor`	`array`	背景色 `[r, g, b]`
`font`	`string`	字型名稱
`fontSize`	`float`	字型大小（pt）
`alignment`	`string`	文字對齊：`left`、`center`、`right`
`maxLength`	`int`	最大字元數（僅文字欄位）
`readonly`	`bool`	禁止使用者編輯
`required`	`bool`	標記為必填（用於表單驗證）
`value`	`string`	預設值 / 初始值

範例：套用自訂屬性

php

$pdf->textField('styled_input', 45, null, 80, 8, [
    'border'    => ['width' => 1, 'color' => [0, 102, 204], 'style' => 'solid'],
    'bgcolor'   => [240, 248, 255],
    'font'      => 'Helvetica',
    'fontSize'  => 11,
    'alignment' => 'left',
    'required'  => true,
    'maxLength' => 50,
]);

JavaScript 動作

表單欄位可以觸發 JavaScript 動作，實現自動計算、驗證與互動：

php

// 按鈕觸發計算
$pdf->buttonField('calc', 15, null, 50, 10, 'Calculate Total',
    'var qty = this.getField("qty").value;'
    . 'var price = this.getField("price").value;'
    . 'this.getField("total").value = qty * price;'
);

常用的內建 JavaScript 函式：

函式	說明
`this.resetForm()`	重設所有表單欄位為預設值
`this.print()`	開啟列印對話框
`submitForm(url)`	將表單資料提交到指定 URL
`this.getField(name)`	取得指定欄位的參考
`app.alert(message)`	顯示警告對話框

表單扁平化（flattenFields）

扁平化會將所有互動式表單欄位轉換為靜態、不可編輯的內容。這在以下場景特別實用：

歸檔已完成的表單，確保內容不被竄改
產生唯讀的最終版 PDF
減少 PDF 檔案的結構複雜度

php

$pdf->flattenFields();  // 將所有表單欄位轉換為靜態內容

扁平化之後，欄位的值會成為永久文字，無法在 PDF 閱讀器中編輯。

注意

扁平化是不可逆的操作。一旦執行，表單欄位將永久轉為靜態內容。如果需要保留互動版本，建議先另存一份副本。

完整範例：客戶資料表

php

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', 'B', 16)
    ->cell(0, 12, 'Customer Registration', newLine: true)
    ->setFont('Helvetica', '', 11)
    ->ln(5)

    // 姓名
    ->cell(30, 8, 'Name:')
    ->textField('name', 45, null, 80, 8, [
        'border'   => ['width' => 1],
        'required' => true,
    ])
    ->ln(12)

    // 電子郵件
    ->cell(30, 8, 'Email:')
    ->textField('email', 45, null, 100, 8, [
        'border' => ['width' => 1],
    ])
    ->ln(12)

    // 國家/地區
    ->cell(30, 8, 'Country:')
    ->comboboxField('country', 45, null, 60, 8, ['TW', 'US', 'UK', 'JP', 'DE'])
    ->ln(12)

    // 性別
    ->cell(30, 8, 'Gender:')
    ->radioField('gender', 45, null, 5, 5, ['value' => 'male'])
    ->cell(10, 5, ' M')
    ->radioField('gender', 65, null, 5, 5, ['value' => 'female'])
    ->cell(10, 5, ' F')
    ->ln(12)

    // 同意條款
    ->checkboxField('agree', 15, null, 5, 5)
    ->cell(0, 5, '  I agree to the terms and conditions', newLine: true)
    ->ln(10)

    // 按鈕
    ->buttonField('submit', 15, null, 40, 10, 'Submit', 'submitForm("https://example.com/register")')
    ->buttonField('reset', 60, null, 40, 10, 'Reset', 'this.resetForm()')
    ->buttonField('print', 105, null, 40, 10, 'Print', 'this.print()');

提示

$y 參數傳入 null 即可使用目前的垂直游標位置，省去手動計算座標的麻煩。
同一群組的單選按鈕必須使用相同的 $name，才能正確形成互斥關係。
表單扁平化適合用在歸檔場景，確保已填寫的資料不會被意外修改。
JavaScript 動作的相容性取決於 PDF 閱讀器，Adobe Acrobat 提供最完整的支援。

表單欄位 ​

快速參考 ​

FormFieldType 列舉 ​

基本範例 ​

文字欄位（textField） ​

核取方塊（checkboxField） ​

單選按鈕（radioField） ​

列表與下拉選單（listboxField / comboboxField） ​

按鈕（buttonField） ​

欄位屬性 ​

範例：套用自訂屬性 ​

JavaScript 動作 ​

表單扁平化（flattenFields） ​

完整範例：客戶資料表 ​

提示 ​