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

PDF가 열릴 때 실행되는 문서 수준 JavaScript를 추가합니다. 함수 정의, 전역 변수 및 초기화 로직에 사용합니다.

매개변수	유형	설명
$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 등)를 사용하십시오.