뷰어 기본 설정과 표시 모드 설정

한눈에 보기

이 레시피에서는 규격을 준수하는 PDF 리더가 문서를 열 때의 표시 방식을 제어합니다. 초기 확대/축소, 페이지 레이아웃, 리더 인터페이스 요소의 표시 여부, 창 크기, 제목 표시줄 텍스트를 설정합니다. 제목 표시줄에는 문서 제목 또는 파일 이름을 표시할 수 있습니다. 이 레시피는 examples/24-viewer-preferences.php를 따릅니다.

설치

composer require nextpdf/core:^3

개념 개요

뷰어 기본 설정은 문서 카탈로그에 저장됩니다. 이는 리더에 전달하는 힌트일 뿐, 보장 사항이 아닙니다. 세 가지 주요 플래그는 다음과 같이 동작합니다. DisplayDocTitle은 제목 표시줄 텍스트를 제어합니다(ISO 32000-2 §12.2). HideToolbar는 리더 도구 모음을 숨긴 보기를 요청합니다. FitWindow는 리더가 창을 첫 페이지에 맞추도록 요청합니다. setDisplayMode()는 초기 확대/축소와 페이지 레이아웃을 함께 지정합니다.

이 프로필은 structural이며, 이는 문서에 트레일러 /ID 값이 포함되기 때문입니다. 후처리 단계에서는 두 실행을 비교하기 전에 해당 값을 정규화합니다.

API 표면

NextPDF\Core\Concerns\HasViewerPreferences(Document에 믹스인됨):

setViewerPreferences(array $prefs): static — HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle(bool)와 같은 키 기반 플래그와 Direction, PrintScaling, Duplex(string), NumCopies(int)를 받습니다.
setDisplayMode(string $zoom = 'default', string $layout = 'SinglePage'): static — $zoom ∈ default | fullpage | fullwidth | real | <numeric>; $layout ∈ SinglePage | OneColumn | TwoColumnLeft | TwoColumnRight | TwoPageLeft | TwoPageRight.

코드 예제 — 빠른 시작

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Presentation Deck');

$doc->setDisplayMode('fullwidth', 'TwoColumnLeft');
$doc->setViewerPreferences([
    'HideToolbar'     => true,
    'FitWindow'       => true,
    'DisplayDocTitle' => true,
]);

$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Opens full-width, two columns, title bar shows the title.', newLine: true);

$doc->save(__DIR__ . '/viewer-prefs.pdf');
echo "Wrote viewer-prefs.pdf\n";

코드 예제 — 프로덕션

아래 전체 예제는 examples/24-viewer-preferences.php를 그대로 반영합니다. 두 열 레이아웃을 확인할 수 있도록 여러 페이지 문서를 만들고, 하니스에서 사용할 수 있도록 NEXTPDF_COOKBOOK_OUTPUT에 지정된 경로에 저장합니다.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Viewer Preferences Demo');
$doc->setAuthor('NextPDF Example');

$doc->setDisplayMode('fullwidth', 'TwoColumnLeft');
$doc->setViewerPreferences([
    'HideToolbar'     => true,
    'HideMenubar'     => true,
    'FitWindow'       => true,
    'CenterWindow'    => true,
    'DisplayDocTitle' => true,
]);

for ($page = 1; $page <= 3; $page++) {
    $doc->addPage();
    $doc->setFont('helvetica', 'B', 18);
    $doc->cell(0, 12, "Page {$page}", newLine: true);
    $doc->setFont('helvetica', '', 11);
    $doc->multiCell(0, 7, 'With TwoColumnLeft layout a conforming reader '
        . 'shows pages side by side. Toolbar and menu bar are hidden, the '
        . 'window fits the first page and is centred, and the title bar '
        . 'shows the document title rather than the filename.');
}

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/viewer-preferences.pdf');

echo "Wrote document with viewer preferences\n";

예상 출력:

Wrote document with viewer preferences

엣지 케이스 및 주의 사항

기본 설정은 권고 사항입니다. ISO 32000-2는 뷰어 기본 설정을 힌트로 정의합니다. 리더는 이 중 어느 설정이든 무시할 수 있습니다. 특히 브라우저는 극히 일부만 반영합니다. 보안 또는 키오스크 동작 보장을 위해 HideToolbar/HideMenubar에 절대 의존하지 마십시오.
DisplayDocTitle에는 제목이 필요합니다. setTitle()이 비어 있지 않은 제목을 설정한 경우에만 동작이 변경됩니다. 제목이 없으면 리더는 결국 파일 이름을 표시합니다.
레이아웃 문자열은 정확해야 합니다. setDisplayMode()는 TwoColumnLeft와 같은 사양에 맞는 철자를 기대하며, two-column-left와 같은 철자는 받지 않습니다. 알 수 없는 레이아웃은 리더 기본값으로 대체됩니다.
숫자 확대/축소 값은 문자열입니다. 150 %인 경우 '150'을 전달하고, 정수 150은 전달하지 마십시오.
단일 페이지와 펼침면. TwoPageLeft/TwoPageRight에는 PDF 1.5+ 리더가 필요합니다. 이전 뷰어는 단일 열 레이아웃으로 다운그레이드됩니다.

성능

뷰어 기본 설정 지정은 렌더링 비용을 발생시키지 않는 상수 시간의 카탈로그 구성 작업입니다. 1000 ms / 64 MB 예산 내에 충분히 머무릅니다.

보안 참고 사항

도구 모음이나 메뉴 모음을 숨기는 것은 표시상의 변경일 뿐입니다. 이는 사용자가 할 수 있는 작업을 제한하지 않습니다. 모든 리더는 키보드 단축키와 마우스 오른쪽 클릭 동작을 유지하며, 많은 리더는 이 플래그를 전혀 따르지 않습니다. 뷰어 기본 설정을 저장, 인쇄, 복사를 제한하는 제어 수단으로 취급하지 마십시오. 그 역할은 권한 비트가 담당하며, 리더는 여전히 협조적으로만 그 권한을 따릅니다. 권한으로 암호화를 참조하십시오.

적합성

설명	사양	조항
`DisplayDocTitle`은 창 제목 표시줄에 문서 제목을 표시할지 여부를 제어합니다.	ISO 32000-2	§12.2
`HideToolbar`는 대화형 도구 모음을 숨기도록 요청합니다.	ISO 32000-2	§12.2
`FitWindow`는 창을 첫 페이지에 맞게 조정하도록 요청합니다.	ISO 32000-2	§12.2

이 기본 설정은 권고적 성격입니다. 인용된 조항은 해당 의미를 정의합니다. 리더가 이를 따라야 한다는 의무를 정의하지는 않습니다. NextPDF는 포괄적인 ISO 32000-2 적합성을 주장하지 않습니다.