Layer (OCG)

I layer PDF — formalmente chiamati Gruppi Contenuto Opzionale (OCG) — ti consentono di creare contenuto che può essere attivato e disattivato nel visualizzatore, o incluso selettivamente durante la stampa. Il sistema layer è gestito tramite Graphics\LayerManager e accessibile tramite l'API fluente Document.

Tutti i metodi restituiscono static, quindi ogni chiamata può essere concatenata.

Riferimento Rapido

Metodo	Scopo
startLayer()	Inizia un nuovo layer con nome dato
endLayer()	Chiudi il layer corrente

Esempio Base

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)

    // Visibile in visualizzatore, non stampato
    ->startLayer('Screen Only', print: false, view: true)
    ->cell(0, 10, 'This text appears on screen but not when printed', newLine: true)
    ->endLayer()

    // Solo stampato
    ->startLayer('Print Only', print: true, view: false)
    ->cell(0, 10, 'This text appears only when printed', newLine: true)
    ->endLayer()

    // Sempre visibile
    ->cell(0, 10, 'This text is always visible', newLine: true);

startLayer()

$pdf->startLayer(string $name, bool $print = true, bool $view = true): static

Inizia un nuovo layer. Tutto il contenuto disegnato dopo questa chiamata appartiene al layer fino a quando endLayer() è chiamato.

Parametro	Tipo	Descrizione
$name	string	Nome visualizzato mostrato nel pannello layer del visualizzatore
$print	bool	Se il contenuto layer appare quando stampato
$view	bool	Se il contenuto layer appare su schermo

endLayer()

Chiude il layer corrente. Il contenuto disegnato dopo questa chiamata non fa più parte di alcun layer.

Modalità Visibilità Layer

La combinazione di $print e $view ti dà quattro modalità visibilità utili:

$print	$view	Comportamento
true	true	Sempre visibile (predefinito)
false	true	Solo schermo — nascosto quando stampato
true	false	Solo stampa — nascosto su schermo
false	false	Inizialmente nascosto ovunque (utente può toggleare)

Layer Annidati

I layer possono essere annidati. Un layer figlio eredita i vincoli visibilità del suo genitore -- se il genitore è nascosto, anche il figlio è nascosto.

$pdf->startLayer('Parent')
    ->cell(0, 10, 'Parent content', newLine: true)
    ->startLayer('Child', print: false, view: true)
    ->cell(0, 10, 'Child content — screen only', newLine: true)
    ->endLayer()
    ->endLayer();

Casi d'Uso

PDF Multi-Lingua

Posiziona ogni traduzione su un layer separato. I lettori toggleano lingue nel pannello layer:

$pdf->startLayer('English')
    ->cell(0, 10, 'Hello, World!', newLine: true)
    ->endLayer()
    ->startLayer('Chinese')
    ->cell(0, 10, '你好，世界！', newLine: true)
    ->endLayer();

Watermark (Solo-Schermo)

$pdf->startLayer('Watermark', print: false, view: true)
    ->setFont('Helvetica', 'B', 48)
    ->setTextColor(200, 200, 200)
    ->text(60, 140, 'DRAFT')
    ->endLayer();

Segni Rifilo Solo-Stampa

$pdf->startLayer('Crop Marks', print: true, view: false)
    ->cropMark(20, 20, 10, 10)
    ->cropMark(190, 20, 10, 10)
    ->endLayer();

Suggerimenti

• I nomi layer dovrebbero essere corti e descrittivi -- appaiono verbatim nel pannello layer del visualizzatore.
• Adobe Acrobat e Foxit Reader hanno supporto OCG completo; i visualizzatori basati browser potrebbero ignorare i layer.
• I layer aggiungono overhead minimale alla dimensione file poiché sono flag metadata, non contenuto duplicato.