ビューアー設定と表示モードを指定する

概要

このレシピでは、準拠した PDF リーダーでドキュメントを開いたときの表示方法を制御します。初期ズーム、ページレイアウト、リーダーのクローム表示、ウィンドウのサイズ調整、タイトルバーのテキストを設定します。タイトルバーには、ドキュメントのタイトルまたはファイル名を表示できます。このレシピは examples/24-viewer-preferences.php に沿っています。

インストール

composer require nextpdf/core:^3

概念の概要

ビューアー設定はドキュメントカタログに格納されます。これらはリーダーに対する ヒント であり、保証ではありません。主要な 3 つのフラグの動作は次のとおりです。DisplayDocTitle はタイトルバーのテキストを制御します（ISO 32000-2 §12.2）。HideToolbar はリーダーのツールバーを非表示にするビューを要求します。FitWindow はリーダーに対し、ウィンドウを最初のページに合わせてサイズ変更するよう要求します。setDisplayMode() は初期ズームとページレイアウトを組み合わせます。

このプロファイルが structural なのは、ドキュメントがトレーラーの /ID 値を保持しているためです。ポストパスは、2 回の実行を比較する前にその値を正規化します。

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 を反映しています。2 段組レイアウトを確認できるように複数ページのドキュメントを構築し、ハーネス用に 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 への包括的な適合を主張するものではありません。