表单字段

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） ​

完整范例：客户资料表 ​

提示 ​