设置查看器首选项和显示模式

概览

这篇 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。