JavaScript

Documentos PDF podem conter JavaScript incorporado que é executado no visualizador. O TCPDF-Next fornece métodos para adicionar scripts em nível de documento através de Content\JavaScriptManager, acessado via a API fluente do Document.

Todos os métodos retornam static, então cada chamada pode ser encadeada.

Referência Rápida

Método	Propósito
includeJS()	Adicionar JavaScript em nível de documento (executa quando o PDF abre)
addJavascriptObject()	Adicionar JavaScript como objeto PDF nomeado

Exemplo Básico

use Yeeefang\TcpdfNext\Core\Document;

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

    // JavaScript em nível de documento
    ->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);
        }
    ')

    // Campos de formulário que usam o 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

O suporte a JavaScript varia por visualizador PDF. Adobe Acrobat possui suporte completo para a API JavaScript do Acrobat. Foxit Reader suporta a maioria das funcionalidades. Visualizadores baseados em navegador e aplicativos de pré-visualização geralmente não executam JavaScript de PDF.

includeJS()

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

Adiciona JavaScript em nível de documento que é executado quando o PDF é aberto. Use para definições de funções, variáveis globais e lógica de inicialização.

Parâmetro	Tipo	Descrição
$script	string	Código JavaScript bruto

Múltiplas chamadas adicionam scripts adicionais. Eles são executados na ordem em que foram adicionados.

addJavascriptObject()

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

Adiciona JavaScript como um objeto PDF nomeado. Útil quando scripts precisam ser referenciados por outros objetos PDF (ações, anotações) em vez de executar na abertura do documento.

Ações JavaScript em Campos de Formulário

Campos de formulário suportam gatilhos de ação JavaScript através do array de opções. Essas ações disparam em resposta à interação do usuário com o campo.

Ação	Gatilho
onFocus	Campo recebe foco
onBlur	Campo perde foco
onChange	Valor do campo muda
validate	Antes do valor ser confirmado
calculate	Quando campos dependentes mudam
format	Após o valor ser confirmado (formatar exibição)
keystroke	Em cada tecla pressionada

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

Gatilho de Impressão e Ações de Abertura

Execute lógica quando o documento é aberto ou impresso:

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

Dicas

• Mantenha scripts concisos. Blocos grandes aumentam o tamanho do arquivo e atrasam a abertura do documento.
• A API JavaScript do Acrobat está documentada na Referência da API JavaScript para Acrobat da Adobe.
• Teste PDFs interativos no Adobe Acrobat para garantir total compatibilidade antes de distribuir.
• Padrões PDF/A proíbem JavaScript. Não inclua scripts se você almeja conformidade PDF/A.
• Para cálculos, use funções embutidas do Acrobat (AFNumber_Format, AFSimple_Calculate, etc.) quando possível.