Capas (OCG)

Las capas PDF — formalmente llamadas Grupos de Contenido Opcionales (OCG) — permiten crear contenido que se puede activar y desactivar en el visor, o incluir selectivamente al imprimir. El sistema de capas se gestiona a través de Graphics\LayerManager y se accede mediante la API fluida de Document.

Todos los métodos retornan static, por lo que cada llamada puede ser encadenada.

Referencia rápida

Método	Propósito
`startLayer()`	Iniciar una nueva capa con un nombre dado
`endLayer()`	Cerrar la capa actual

Ejemplo básico

php

use Yeeefang\TcpdfNext\Core\Document;

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

    // Visible en el visor, no se imprime
    ->startLayer('Screen Only', print: false, view: true)
    ->cell(0, 10, 'This text appears on screen but not when printed', newLine: true)
    ->endLayer()

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

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

startLayer()

php

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

Inicia una nueva capa. Todo el contenido dibujado después de esta llamada pertenece a la capa hasta que se llama a endLayer().

Parámetro	Tipo	Descripción
`$name`	`string`	Nombre para mostrar en el panel de capas del visor
`$print`	`bool`	Si el contenido de la capa aparece al imprimir
`$view`	`bool`	Si el contenido de la capa aparece en pantalla

endLayer()

Cierra la capa actual. El contenido dibujado después de esta llamada ya no es parte de ninguna capa.

Modos de visibilidad de capas

La combinación de $print y $view te da cuatro modos de visibilidad útiles:

`$print`	`$view`	Comportamiento
`true`	`true`	Siempre visible (predeterminado)
`false`	`true`	Solo pantalla — oculto al imprimir
`true`	`false`	Solo impresión — oculto en pantalla
`false`	`false`	Inicialmente oculto en todas partes (el usuario puede conmutar)

Capas anidadas

Las capas pueden anidarse. Una capa hija hereda las restricciones de visibilidad de su padre — si el padre está oculto, la hija también lo está.

php

$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();

Casos de uso

PDFs multilingües

Coloca cada traducción en una capa separada. Los lectores conmutan idiomas en el panel de capas:

php

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

Marca de agua (solo pantalla)

php

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

Marcas de corte (solo impresión)

php

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

Consejos

Los nombres de capas deben ser cortos y descriptivos — aparecen literalmente en el panel de capas del visor.
Adobe Acrobat y Foxit Reader tienen soporte completo de OCG; los visores basados en navegador pueden ignorar las capas.
Las capas agregan una sobrecarga mínima al tamaño del archivo ya que son indicadores de metadatos, no contenido duplicado.

Capas (OCG) ​

Referencia rápida ​

Ejemplo básico ​

startLayer() ​

endLayer() ​

Modos de visibilidad de capas ​

Capas anidadas ​

Casos de uso ​

PDFs multilingües ​

Marca de agua (solo pantalla) ​

Marcas de corte (solo impresión) ​

Consejos ​