JavaScript

PDF 文件可以包含在閱讀器中執行的嵌入式 JavaScript。TCPDF-Next 透過 Content\JavaScriptManager 提供新增文件級腳本的方法，並經由 Document 流暢 API 存取。

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

快速參考

方法	用途
includeJS()	新增文件級 JavaScript（PDF 開啟時執行）
addJavascriptObject()	將 JavaScript 新增為具名 PDF 物件

基本範例

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()

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

新增文件級 JavaScript，在 PDF 開啟時執行。適用於函式定義、全域變數與初始化邏輯。

參數	型別	說明
$script	string	原始 JavaScript 程式碼

可多次呼叫以追加額外腳本，腳本會按新增順序依序執行。

addJavascriptObject()

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

將 JavaScript 新增為具名 PDF 物件。當腳本需要被其他 PDF 物件（動作、註解）引用，而非在文件開啟時執行時特別有用。

表單欄位的 JavaScript 動作

表單欄位透過選項陣列支援 JavaScript 動作觸發。這些動作會在使用者與欄位互動時觸發。

動作	觸發時機
onFocus	欄位獲得焦點
onBlur	欄位失去焦點
onChange	欄位值改變
validate	值提交前進行驗證
calculate	相依欄位變更時觸發計算
format	值提交後進行格式化顯示
keystroke	每次按鍵輸入時觸發

$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; }',
]);

列印觸發與開啟動作

在文件開啟或列印時執行邏輯：

$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 等）。