Impostare le preferenze del visualizzatore e la modalità di visualizzazione

In breve

Questa ricetta mostra come controllare il modo in cui un lettore PDF conforme presenta il documento al momento dell’apertura. È possibile impostare lo zoom iniziale, il layout della pagina, la visibilità dei controlli del lettore, le dimensioni della finestra e il testo della barra del titolo. La barra del titolo può mostrare il titolo del documento oppure il nome del file. La ricetta si basa su examples/24-viewer-preferences.php.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Le preferenze del visualizzatore sono memorizzate nel catalogo del documento. Sono suggerimenti per il lettore, non garanzie. I tre flag principali funzionano nel modo seguente. DisplayDocTitle controlla il testo della barra del titolo (ISO 32000-2 §12.2). HideToolbar richiede una visualizzazione senza la barra degli strumenti del lettore. FitWindow chiede al lettore di adattare le dimensioni della finestra alla prima pagina. setDisplayMode() abbina uno zoom iniziale a un layout di pagina.

Il profilo è structural perché il trailer del documento contiene un valore /ID. Il post-pass normalizza tale valore prima di confrontare due esecuzioni.

Superficie dell’API

NextPDF\Core\Concerns\HasViewerPreferences (incorporato in Document):

setViewerPreferences(array $prefs): static — flag con chiavi come HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool) e 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.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

L’esempio completo seguente rispecchia examples/24-viewer-preferences.php. Crea un documento multipagina in modo da rendere visibile il layout a due colonne e scrive su NEXTPDF_COOKBOOK_OUTPUT per l’harness.

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

Output previsto:

Wrote document with viewer preferences

Casi limite e insidie

Le preferenze sono indicative. ISO 32000-2 definisce le preferenze del visualizzatore come suggerimenti. I lettori possono ignorare qualunque preferenza. I browser, in particolare, ne rispettano pochissime. Non affidarsi mai a HideToolbar/HideMenubar per ottenere una garanzia di sicurezza o di modalità chiosco.
DisplayDocTitle richiede un titolo. Incide sul comportamento solo quando setTitle() ha impostato un titolo non vuoto. In assenza di un titolo, il lettore mostra comunque il nome del file.
Le stringhe di layout sono esatte. setDisplayMode() richiede le grafie definite dalla specifica, ad esempio TwoColumnLeft, non two-column-left. Un layout sconosciuto fa usare al lettore il valore predefinito.
Lo zoom numerico è una stringa. Passare '150' per 150 %, non il numero intero 150.
Pagina singola e pagine affiancate. TwoPageLeft/TwoPageRight richiedono lettori PDF 1.5+. I visualizzatori meno recenti ripiegano su un layout a colonna singola.

Prestazioni

L’impostazione delle preferenze del visualizzatore è una configurazione del catalogo a tempo costante, senza costi di rendering. Rimane ampiamente entro il budget di 1000 ms / 64 MB.

Note sulla sicurezza

Nascondere la barra degli strumenti o la barra dei menu è una scelta estetica. Non limita ciò che l’utente può fare. Ogni lettore mantiene le scorciatoie da tastiera e le azioni del clic destro, e molti ignorano del tutto i flag. Le preferenze del visualizzatore non vanno considerate un controllo che limita il salvataggio, la stampa o la copia. Questo compito spetta ai bit di autorizzazione, che i lettori rispettano comunque solo in modo cooperativo. Vedere Cifrare con autorizzazioni.

Conformità

Dichiarazione	Specifica	Clausola
`DisplayDocTitle` controlla se la barra del titolo della finestra mostra il titolo del documento.	ISO 32000-2	§12.2
`HideToolbar` richiede che la barra degli strumenti interattiva sia nascosta.	ISO 32000-2	§12.2
`FitWindow` richiede che la finestra sia ridimensionata in base alla prima pagina.	ISO 32000-2	§12.2

Si tratta di preferenze indicative. Le clausole citate ne definiscono il significato. Non impongono a un lettore l’obbligo di rispettarle. NextPDF non dichiara una conformità generale a ISO 32000-2.