Configure as preferências de visualização e o modo de exibição

Visão geral

Esta receita controla como um leitor de Portable Document Format (PDF) em conformidade exibe o documento ao abri-lo. Você define o zoom inicial, o layout da página, os controles do leitor, o tamanho da janela e o texto da barra de título. A barra de título pode mostrar o título do documento ou o nome do arquivo. Esta receita segue examples/24-viewer-preferences.php.

Instalação

composer require nextpdf/core:^3

Visão conceitual

As preferências de visualização ficam no catálogo do documento. Elas são dicas para o leitor, não garantias. Use as três flags principais assim. DisplayDocTitle controla o texto da barra de título (ISO 32000-2 §12.2). HideToolbar pede ao leitor que oculte a barra de ferramentas. FitWindow pede ao leitor que redimensione a janela para que ela se ajuste à primeira página. setDisplayMode() combina um zoom inicial com um layout de página.

O perfil é structural porque o documento carrega um valor /ID no trailer. O pós-processamento normaliza esse valor antes de comparar duas execuções.

Superfície da API

NextPDF\Core\Concerns\HasViewerPreferences (incorporado em Document):

setViewerPreferences(array $prefs): static — flags por chave, como HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool), além de 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.

Exemplo de código — Início rápido

<?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";

Exemplo de código — Produção

O exemplo completo abaixo espelha examples/24-viewer-preferences.php. Ele cria um documento de várias páginas para que você veja o layout de duas colunas e grava em NEXTPDF_COOKBOOK_OUTPUT para o ambiente de testes.

<?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";

Saída esperada:

Wrote document with viewer preferences

Casos extremos e armadilhas

As preferências são consultivas. A ISO 32000-2 define as preferências de visualização como dicas. Os leitores podem ignorar qualquer uma delas. Os navegadores, em particular, respeitam muito poucas. Nunca confie em HideToolbar/HideMenubar como garantia de segurança ou de modo quiosque.
DisplayDocTitle precisa de um título. Ele só altera o comportamento quando setTitle() define um título não vazio. Sem um título, o leitor ainda mostra o nome do arquivo.
As strings de layout são exatas. setDisplayMode() espera as grafias da especificação, como TwoColumnLeft, não two-column-left. Um layout desconhecido faz o leitor usar o padrão dele.
O zoom numérico é uma string. Passe '150' para 150 %, não o inteiro 150.
Página única vs. duas páginas lado a lado. TwoPageLeft/TwoPageRight exigem leitores PDF 1.5+. Leitores mais antigos usam um layout de coluna única.

Desempenho

Definir as preferências de visualização é uma configuração de catálogo em tempo constante e não tem custo de renderização. Ela permanece bem dentro do orçamento de 1000 ms / 64 MB.

Notas de segurança

Ocultar a barra de ferramentas ou a barra de menus é cosmético. Isso não restringe o que você pode fazer. Todo leitor mantém os atalhos de teclado e as ações de clique com o botão direito, e muitos ignoram as flags por completo. Não trate as preferências de visualização como um controle que limita salvar, imprimir ou copiar. Os bits de permissão tratam dessas solicitações e, ainda assim, os leitores só as respeitam de forma cooperativa. Consulte Criptografar com permissões.

Conformidade

Declaração	Especificação	Cláusula
`DisplayDocTitle` controla se a barra de título da janela mostra o título do documento.	ISO 32000-2	§12.2
`HideToolbar` solicita que a barra de ferramentas interativa seja ocultada.	ISO 32000-2	§12.2
`FitWindow` solicita que a janela seja redimensionada para a primeira página.	ISO 32000-2	§12.2

Essas preferências são consultivas. As cláusulas citadas definem o significado delas. Elas não definem a obrigação de um leitor de respeitá-las. O NextPDF não declara conformidade irrestrita com a ISO 32000-2.