Настройка параметров просмотра и режима отображения

Кратко

Этот рецепт задаёт, как совместимая программа просмотра Portable Document Format (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";

Пример кода — production

Полный пример ниже повторяет 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.