Calques (OCG)

Les calques PDF — formellement appelés Groupes de Contenu Optionnel (OCG) — permettent de créer du contenu qui peut être activé ou désactivé dans le lecteur, ou inclus sélectivement lors de l'impression. Le système de calques est géré via Graphics\LayerManager et accessible via l'API fluent de Document.

Toutes les méthodes retournent static, permettant le chaînage.

Référence rapide

Méthode	Objectif
startLayer()	Démarrer un nouveau calque avec un nom donné
endLayer()	Fermer le calque actuel

Exemple de base

use Yeeefang\TcpdfNext\Core\Document;

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

    // Visible dans le lecteur, non imprimé
    ->startLayer('Écran uniquement', print: false, view: true)
    ->cell(0, 10, 'Ce texte apparaît à l'écran mais pas à l'impression', newLine: true)
    ->endLayer()

    // Imprimé uniquement
    ->startLayer('Impression uniquement', print: true, view: false)
    ->cell(0, 10, 'Ce texte apparaît uniquement à l'impression', newLine: true)
    ->endLayer()

    // Toujours visible
    ->cell(0, 10, 'Ce texte est toujours visible', newLine: true);

startLayer()

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

Démarre un nouveau calque. Tout le contenu dessiné après cet appel appartient au calque jusqu'à l'appel de endLayer().

Paramètre	Type	Description
$name	string	Nom d'affichage montré dans le panneau de calques du lecteur
$print	bool	Si le contenu du calque apparaît lors de l'impression
$view	bool	Si le contenu du calque apparaît à l'écran

endLayer()

Ferme le calque actuel. Le contenu dessiné après cet appel ne fait plus partie d'aucun calque.

Modes de visibilité de calque

La combinaison de $print et $view donne quatre modes de visibilité utiles :

$print	$view	Comportement
true	true	Toujours visible (par défaut)
false	true	Écran uniquement — caché à l'impression
true	false	Impression uniquement — caché à l'écran
false	false	Initialement caché partout (l'utilisateur peut basculer)

Calques imbriqués

Les calques peuvent être imbriqués. Un calque enfant hérite des contraintes de visibilité de son parent — si le parent est caché, l'enfant l'est aussi.

$pdf->startLayer('Parent')
    ->cell(0, 10, 'Contenu parent', newLine: true)
    ->startLayer('Enfant', print: false, view: true)
    ->cell(0, 10, 'Contenu enfant — écran uniquement', newLine: true)
    ->endLayer()
    ->endLayer();

Cas d'usage

PDF multilingues

Placer chaque traduction sur un calque séparé. Les lecteurs basculent les langues dans le panneau de calques :

$pdf->startLayer('Français')
    ->cell(0, 10, 'Bonjour, monde !', newLine: true)
    ->endLayer()
    ->startLayer('Anglais')
    ->cell(0, 10, 'Hello, World!', newLine: true)
    ->endLayer();

Filigrane (écran uniquement)

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

Traits de coupe (impression uniquement)

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

Conseils

• Les noms de calques doivent être courts et descriptifs — ils apparaissent textuellement dans le panneau de calques du lecteur.
• Adobe Acrobat et Foxit Reader ont un support OCG complet ; les lecteurs basés sur navigateur peuvent ignorer les calques.
• Les calques ajoutent un overhead minimal à la taille du fichier car ce sont des drapeaux de métadonnées, pas du contenu dupliqué.