設定檢視器偏好設定與顯示模式

概覽

這則 recipe（範例）用來控制相容的 PDF 閱讀器在開啟你的文件時的呈現方式。你可以設定初始縮放、頁面版面配置、是否顯示閱讀器介面、視窗尺寸，以及標題列文字。標題列可以顯示文件標題或檔名。這則範例對應 examples/24-viewer-preferences.php。

安裝

composer require nextpdf/core:^3

概念說明

檢視器偏好設定存放在文件的 catalog（型錄）中。它們是給閱讀器的提示，而非保證。三個主要旗標的運作方式如下：DisplayDocTitle 控制標題列文字（ISO 32000-2 §12.2）；HideToolbar 要求閱讀器以不含工具列的檢視呈現；FitWindow 要求閱讀器將視窗縮放成符合第一頁的大小。setDisplayMode() 會一併設定初始縮放與頁面版面配置。

這份設定屬於 structural，因為文件帶有 trailer 的 /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 作為資訊安全或 kiosk 模式的保證。
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。