Configurar las preferencias de visualización y el modo de visualización

De un vistazo

Esta receta permite controlar cómo un lector de PDF conforme presenta el documento al abrirlo. Con ella se configuran el zoom inicial, el diseño de página, la visibilidad de la interfaz del lector, el tamaño de la ventana y el texto de la barra de título. La barra de título puede mostrar el título del documento o el nombre del archivo. La receta sigue examples/24-viewer-preferences.php.

Instalación

composer require nextpdf/core:^3

Resumen conceptual

Las preferencias de visualización residen en el catálogo del documento. Son indicaciones para el lector, no garantías. Los tres indicadores principales se comportan de la siguiente manera. DisplayDocTitle controla el texto de la barra de título (ISO 32000-2 §12.2). HideToolbar solicita ocultar la barra de herramientas del lector. FitWindow pide al lector que ajuste el tamaño de su ventana a la primera página. setDisplayMode() combina un zoom inicial con un diseño de página.

El perfil es structural porque el documento incluye un valor /ID en el tráiler. La pasada de posprocesamiento normaliza ese valor antes de comparar dos ejecuciones.

Superficie de la API

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

setViewerPreferences(array $prefs): static: indicadores con claves como HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool), y 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.

Ejemplo de código — Inicio 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";

Ejemplo de código — Producción

El ejemplo completo siguiente refleja examples/24-viewer-preferences.php. Construye un documento de varias páginas para que el diseño de dos columnas sea visible y escribe en NEXTPDF_COOKBOOK_OUTPUT para el arnés.

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

Salida esperada:

Wrote document with viewer preferences

Casos límite y trampas

Las preferencias son orientativas. ISO 32000-2 define las preferencias de visualización como indicaciones. Los lectores pueden ignorar cualquiera de ellas. Los navegadores, en particular, respetan muy pocas. Nunca se debe confiar en HideToolbar/HideMenubar como garantía de seguridad o de modo quiosco.
DisplayDocTitle necesita un título. Solo cambia el comportamiento cuando setTitle() ha establecido un título no vacío. Sin título, el lector muestra el nombre del archivo de todos modos.
Las cadenas de diseño son exactas. setDisplayMode() espera las grafías de la especificación, como TwoColumnLeft, no two-column-left. Un diseño desconocido recurre al valor predeterminado del lector.
El zoom numérico es una cadena. Pasar '150' para 150 %, no el entero 150.
Página única frente a doble página. TwoPageLeft/TwoPageRight necesitan lectores PDF 1.5+. Los visores más antiguos lo degradan a un diseño de una sola columna.

Rendimiento

Configurar las preferencias de visualización solo actualiza el catálogo en tiempo constante, sin coste de renderizado. Se mantiene holgadamente dentro del presupuesto de 1000 ms / 64 MB.

Notas de seguridad

Ocultar la barra de herramientas o la barra de menús es una medida cosmética. No restringe lo que el usuario puede hacer. Todos los lectores conservan los atajos de teclado y las acciones de clic derecho, y muchos ignoran los indicadores por completo. No se deben tratar las preferencias de visualización como un control que limite el guardado, la impresión o la copia. Esa función corresponde a los bits de permisos, que los lectores solo respetan de forma cooperativa. Consultar Cifrar con permisos.

Conformidad

Declaración	Especificación	Cláusula
`DisplayDocTitle` controla si la barra de título de la ventana muestra el título del documento.	ISO 32000-2	§12.2
`HideToolbar` solicita que se oculte la barra de herramientas interactiva.	ISO 32000-2	§12.2
`FitWindow` solicita que se ajuste la ventana a la primera página.	ISO 32000-2	§12.2

Se trata de preferencias orientativas. Las cláusulas citadas definen su significado. No establecen la obligación de que un lector las respete. NextPDF no afirma una conformidad general con ISO 32000-2.