Camadas (OCG)

Camadas PDF — formalmente chamadas de Optional Content Groups (OCG) — permitem criar conteúdo que pode ser alternado no visualizador ou incluído seletivamente ao imprimir. O sistema de camadas é gerenciado através de Graphics\LayerManager e 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
`startLayer()`	Iniciar nova camada com nome dado
`endLayer()`	Fechar camada atual

Exemplo Básico

php

use Yeeefang\TcpdfNext\Core\Document;

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

    // Visível no visualizador, não impresso
    ->startLayer('Screen Only', print: false, view: true)
    ->cell(0, 10, 'This text appears on screen but not when printed', newLine: true)
    ->endLayer()

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

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

startLayer()

php

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

Inicia uma nova camada. Todo conteúdo desenhado após esta chamada pertence à camada até que endLayer() seja chamado.

Parâmetro	Tipo	Descrição
`$name`	`string`	Nome de exibição mostrado no painel de camadas do visualizador
`$print`	`bool`	Se o conteúdo da camada aparece quando impresso
`$view`	`bool`	Se o conteúdo da camada aparece na tela

endLayer()

Fecha a camada atual. Conteúdo desenhado após esta chamada não faz mais parte de nenhuma camada.

Modos de Visibilidade de Camada

A combinação de $print e $view oferece quatro modos úteis de visibilidade:

`$print`	`$view`	Comportamento
`true`	`true`	Sempre visível (padrão)
`false`	`true`	Apenas tela — oculto quando impresso
`true`	`false`	Apenas impressão — oculto na tela
`false`	`false`	Inicialmente oculto em todo lugar (usuário pode alternar)

Camadas Aninhadas

Camadas podem ser aninhadas. Uma camada filha herda as restrições de visibilidade de sua camada pai -- se a pai está oculta, a filha também 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 Multi-Idioma

Coloque cada tradução em uma camada separada. Leitores alternam idiomas no painel de camadas:

php

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

Marca d'água (Apenas Tela)

php

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

Marcas de Corte (Apenas Impressão)

php

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

Dicas

Nomes de camadas devem ser curtos e descritivos -- eles aparecem literalmente no painel de camadas do visualizador.
Adobe Acrobat e Foxit Reader possuem suporte completo a OCG; visualizadores baseados em navegador podem ignorar camadas.
Camadas adicionam sobrecarga mínima ao tamanho do arquivo pois são flags de metadados, não conteúdo duplicado.

Camadas (OCG) ​

Referência Rápida ​

Exemplo Básico ​

startLayer() ​

endLayer() ​

Modos de Visibilidade de Camada ​

Camadas Aninhadas ​

Casos de Uso ​

PDFs Multi-Idioma ​

Marca d'água (Apenas Tela) ​

Marcas de Corte (Apenas Impressão) ​

Dicas ​