JavaScript 管理¶

PDF 2.0 支援嵌入 JavaScript（基於 Acrobat JavaScript API，即 AcroJS）用於互動式表單計算、驗證邏輯與動態行為。NextPDF 提供 JavaScriptManager 統一管理文件中所有 JavaScript 動作，並在輸出時確保腳本的安全封裝。

安全提醒：PDF JavaScript 在部分 PDF 閱讀器中預設停用，且可能被視為安全風險。僅在使用者明確知情且有必要的場合嵌入 JavaScript，切勿用於惡意用途。

文件層級 JavaScript¶

文件層級腳本在 PDF 開啟時自動執行：

use NextPDF\Content\JavaScriptManager;

$document->javascript()->addDocumentScript(
    name: 'init',
    script: <<<JS
    // 初始化計算欄位
    var subtotal = this.getField("subtotal");
    var tax = this.getField("tax");
    var total = this.getField("total");

    total.value = subtotal.value * (1 + tax.value / 100);
    JS,
);

頁面層級 JavaScript¶

頁面層級腳本在特定頁面開啟或關閉時執行：

// 頁面開啟時執行
$document->javascript()->addPageScript(
    pageNumber: 1,
    trigger: PageScriptTrigger::Open,
    script: 'app.alert("Welcome to page 1!");',
);

// 頁面關閉時執行
$document->javascript()->addPageScript(
    pageNumber: 2,
    trigger: PageScriptTrigger::Close,
    script: 'this.submitForm({cURL: "https://api.example.com/track"});',
);

表單欄位動作¶

use NextPDF\Form\FieldAction;

// 為表單欄位附加計算腳本
$document->form()->field('subtotal')->addAction(
    trigger: FieldAction::Calculate,
    script: <<<JS
    var qty = this.getField("quantity").value;
    var price = this.getField("unit_price").value;
    event.value = qty * price;
    JS,
);

// 欄位驗證腳本
$document->form()->field('email')->addAction(
    trigger: FieldAction::Validate,
    script: <<<JS
    var re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!re.test(event.value)) {
        app.alert("Please enter a valid email address.");
        event.rc = false;
    }
    JS,
);

外部 JavaScript 檔案¶

// 從檔案載入腳本（建議用於大型腳本庫）
$document->javascript()->addFromFile(
    name: 'calculations',
    path: '/path/to/scripts/calculations.js',
);

安全性考量¶

// 啟用腳本內容驗證（掃描潛在危險的 API 呼叫）
$document->javascript()->setSecurityLevel(
    level: JavaScriptSecurityLevel::Strict,
);

AcroJS API 支援矩陣¶

API 類別	支援狀態	備註
`app.*`	部分	`app.alert`、`app.response`
`this.*`	完整	完整表單欄位 API
`event.*`	完整	動作事件物件
`util.*`	部分	日期格式化、字串工具
`net.*`	受限	僅 HTTPS 提交

參見¶

AcroForm — 互動式表單欄位
連結 — PDF 動作連結（非 JavaScript）
安全性 — 腳本執行的文件權限設定