JavaScript

PDF 文件可以包含在阅读器中执行的嵌入式 JavaScript。TCPDF-Next 通过 Content\JavaScriptManager 提供添加文件级脚本的方法，并经由 Document 流畅 API 访问。

所有方法皆返回 static，因此可以链式串接。

快速参考

方法	用途
`includeJS()`	添加文件级 JavaScript（PDF 打开时执行）
`addJavascriptObject()`	将 JavaScript 添加为具名 PDF 对象

基本范例

php

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Interactive Form with JavaScript', newLine: true)

    // 文件级 JavaScript
    ->includeJS('
        function validateEmail(field) {
            var email = field.value;
            var re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
            if (!re.test(email)) {
                app.alert("Please enter a valid email address.");
                return false;
            }
            return true;
        }

        function calculateTotal() {
            var qty = this.getField("qty").value;
            var price = this.getField("price").value;
            this.getField("total").value = (qty * price).toFixed(2);
        }
    ')

    // 使用 JavaScript 的表单字段
    ->textField('email', 45, null, 80, 8, [
        'onBlur' => 'validateEmail(event.target)',
    ])
    ->textField('qty', 45, null, 30, 8)
    ->textField('price', 80, null, 30, 8)
    ->textField('total', 115, null, 40, 8, [
        'readonly' => true,
    ]);

WARNING

JavaScript 支持程度因 PDF 阅读器而异。Adobe Acrobat 完整支持 Acrobat JavaScript API；Foxit Reader 支持大部分功能；浏览器内置的查看器与系统预览程序通常不会执行 PDF JavaScript。

includeJS()

php

$pdf->includeJS(string $script): static

添加文件级 JavaScript，在 PDF 打开时执行。适用于函数定义、全局变量与初始化逻辑。

参数	类型	说明
`$script`	`string`	原始 JavaScript 代码

可多次调用以追加额外脚本，脚本会按添加顺序依序执行。

addJavascriptObject()

php

$pdf->addJavascriptObject(string $script): static

将 JavaScript 添加为具名 PDF 对象。当脚本需要被其他 PDF 对象（动作、注解）引用，而非在文件打开时执行时特别有用。

表单字段的 JavaScript 动作

表单字段通过选项数组支持 JavaScript 动作触发。这些动作会在用户与字段交互时触发。

动作	触发时机
`onFocus`	字段获得焦点
`onBlur`	字段失去焦点
`onChange`	字段值改变
`validate`	值提交前进行验证
`calculate`	依赖字段变更时触发计算
`format`	值提交后进行格式化显示
`keystroke`	每次按键输入时触发

php

$pdf->textField('price', 45, null, 40, 8, [
    'format'    => 'AFNumber_Format(2, 0, 0, 0, "$", true);',
    'keystroke' => 'AFNumber_Keystroke(2, 0, 0, 0, "$", true);',
    'validate'  => 'if (event.value < 0) { app.alert("Price cannot be negative."); event.rc = false; }',
]);

打印触发与打开动作

在文件打开或打印时执行逻辑：

php

$pdf->includeJS('
    app.alert("Welcome! Please fill in all required fields.");
')
->includeJS('
    var pp = this.addScript("willPrint", "app.alert(\'This document is confidential.\');");
');

提示

脚本应尽量精简。过大的代码块会增加文件大小并拖慢文件打开速度。
Acrobat JavaScript API 的完整文档请参考 Adobe 的 JavaScript for Acrobat API Reference。
发布前请在 Adobe Acrobat 中测试交互式 PDF，以确保完整兼容性。
PDF/A 标准禁止使用 JavaScript。若目标为 PDF/A 合规，请勿加入脚本。
进行计算时，尽量使用 Acrobat 内置函数（AFNumber_Format、AFSimple_Calculate 等）。

JavaScript ​

快速参考 ​

基本范例 ​

includeJS() ​

addJavascriptObject() ​

表单字段的 JavaScript 动作 ​

打印触发与打开动作 ​

提示 ​