Слои (OCG)

PDF-слои — формально называемые Optional Content Groups (OCG) — позволяют создавать контент, который можно включать и выключать в просмотрщике или выборочно включать при печати. Система слоёв управляется через Graphics\LayerManager и доступна через fluent API класса Document.

Все методы возвращают static, поэтому каждый вызов может быть объединён в цепочку.

Краткий справочник

Метод	Назначение
`startLayer()`	Начать новый слой с указанным именем
`endLayer()`	Закрыть текущий слой

Базовый пример

php

use Yeeefang\TcpdfNext\Core\Document;

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

    // Видим в просмотрщике, не печатается
    ->startLayer('Screen Only', print: false, view: true)
    ->cell(0, 10, 'This text appears on screen but not when printed', newLine: true)
    ->endLayer()

    // Только для печати
    ->startLayer('Print Only', print: true, view: false)
    ->cell(0, 10, 'This text appears only when printed', newLine: true)
    ->endLayer()

    // Всегда видим
    ->cell(0, 10, 'This text is always visible', newLine: true);

startLayer()

php

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

Начинает новый слой. Весь контент, нарисованный после этого вызова, принадлежит слою до вызова endLayer().

Параметр	Тип	Описание
`$name`	`string`	Отображаемое имя в панели слоёв просмотрщика
`$print`	`bool`	Отображается ли контент слоя при печати
`$view`	`bool`	Отображается ли контент слоя на экране

endLayer()

Закрывает текущий слой. Контент, нарисованный после этого вызова, больше не является частью слоя.

Режимы видимости слоёв

Комбинация $print и $view даёт четыре полезных режима видимости:

`$print`	`$view`	Поведение
`true`	`true`	Всегда видим (по умолчанию)
`false`	`true`	Только на экране — скрыт при печати
`true`	`false`	Только при печати — скрыт на экране
`false`	`false`	Изначально скрыт везде (пользователь может переключить)

Вложенные слои

Слои могут быть вложенными. Дочерний слой наследует ограничения видимости родителя — если родитель скрыт, дочерний тоже скрыт.

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

Сценарии использования

Многоязычные PDF

Разместите каждый перевод на отдельном слое. Читатели переключают языки в панели слоёв:

php

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

Водяной знак (только на экране)

php

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

Метки обрезки (только при печати)

php

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

Советы

Имена слоёв должны быть короткими и описательными — они отображаются в панели слоёв просмотрщика.
Adobe Acrobat и Foxit Reader полностью поддерживают OCG; браузерные просмотрщики могут игнорировать слои.
Слои добавляют минимальные накладные расходы к размеру файла, так как являются метаданными, а не дублированным контентом.

Слои (OCG) ​

Краткий справочник ​

Базовый пример ​

startLayer() ​

endLayer() ​

Режимы видимости слоёв ​

Вложенные слои ​

Сценарии использования ​

Многоязычные PDF ​

Водяной знак (только на экране) ​

Метки обрезки (только при печати) ​

Советы ​