레이어 (OCG)

PDF 레이어 -- 공식적으로 선택적 콘텐츠 그룹(OCG)이라고 합니다 -- 는 뷰어에서 켜고 끌 수 있거나, 인쇄 시 선택적으로 포함할 수 있는 콘텐츠를 생성할 수 있게 합니다. 레이어 시스템은 Graphics\LayerManager를 통해 관리되며 Document 플루언트 API를 통해 접근합니다.

모든 메서드는 static을 반환하므로 모든 호출을 체이닝할 수 있습니다.

빠른 참조

메서드	용도
startLayer()	주어진 이름으로 새 레이어 시작
endLayer()	현재 레이어 닫기

기본 예제

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

$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	모든 곳에서 초기에 숨김 (사용자가 토글 가능)

중첩 레이어

레이어는 중첩할 수 있습니다. 자식 레이어는 부모의 가시성 제약을 상속합니다 -- 부모가 숨겨지면 자식도 숨겨집니다.

$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

각 번역을 별도의 레이어에 배치합니다. 리더는 레이어 패널에서 언어를 전환합니다:

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

워터마크 (화면 전용)

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

인쇄 전용 재단 표시

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

팁

• 레이어 이름은 짧고 설명적이어야 합니다 -- 뷰어의 레이어 패널에 그대로 표시됩니다.
• Adobe Acrobat과 Foxit Reader는 OCG를 완전히 지원합니다. 브라우저 기반 뷰어는 레이어를 무시할 수 있습니다.
• 레이어는 메타데이터 플래그이므로 중복 콘텐츠가 아니어서 파일 크기에 최소한의 오버헤드만 추가합니다.