Définir les préférences d’affichage et le mode de présentation

En bref

Cette recette contrôle la façon dont un lecteur PDF conforme présente ton document à l’ouverture. Tu définis le zoom initial, la disposition des pages, la visibilité de l’interface du lecteur, le dimensionnement de la fenêtre et le texte de la barre de titre. La barre de titre peut afficher le titre du document ou le nom du fichier. Cette recette suit examples/24-viewer-preferences.php.

Installation

composer require nextpdf/core:^3

Vue d’ensemble conceptuelle

Les préférences d’affichage résident dans le catalogue du document. Ce sont des indications destinées au lecteur, pas des garanties. Les trois drapeaux principaux fonctionnent ainsi : DisplayDocTitle contrôle le texte de la barre de titre (ISO 32000-2 §12.2). HideToolbar demande un affichage sans la barre d’outils du lecteur. FitWindow demande au lecteur de redimensionner sa fenêtre à la taille de la première page. setDisplayMode() associe un zoom initial à une disposition des pages.

Le profil est structural parce que le document contient une valeur /ID dans le trailer. La passe finale normalise cette valeur avant de comparer deux exécutions.

Surface de l’API

NextPDF\Core\Concerns\HasViewerPreferences (intégré dans Document) :

setViewerPreferences(array $prefs): static — accepte des drapeaux nommés tels que HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool), ainsi que 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.

Exemple de code — Démarrage rapide

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

Exemple de code — Production

L’exemple complet ci-dessous reproduit examples/24-viewer-preferences.php. Il construit un document multipage pour bien montrer la disposition en deux colonnes, et il écrit dans NEXTPDF_COOKBOOK_OUTPUT pour le harnais de test.

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

Sortie attendue :

Wrote document with viewer preferences

Cas limites & pièges

Les préférences sont indicatives. ISO 32000-2 définit les préférences d’affichage comme des indications. Les lecteurs peuvent en ignorer une ou plusieurs. Les navigateurs, en particulier, en honorent très peu. Ne t’appuie jamais sur HideToolbar/HideMenubar pour garantir la sécurité ou un mode kiosque.
DisplayDocTitle a besoin d’un titre. Ce drapeau ne change le comportement que si setTitle() a défini un titre non vide. Sans titre, le lecteur affiche dans tous les cas le nom du fichier.
Les chaînes de disposition doivent être exactes. setDisplayMode() attend l’orthographe de la spécification, comme TwoColumnLeft, et non two-column-left. Une disposition inconnue revient à la disposition par défaut du lecteur.
Le zoom numérique est une chaîne. Passe '150' pour 150 %, et non l’entier 150.
Page simple ou double. TwoPageLeft/TwoPageRight nécessitent des lecteurs PDF 1.5+. Les visionneuses plus anciennes se rabattent sur une disposition à une seule colonne.

Performance

Définir les préférences d’affichage configure le catalogue en temps constant, sans coût de rendu. Cela reste largement dans le budget de 1000 ms / 64 Mo.

Notes de sécurité

Masquer la barre d’outils ou la barre de menus relève du cosmétique. Cela ne restreint pas les actions de l’utilisateur. Chaque lecteur conserve les raccourcis clavier et les actions du clic droit, et beaucoup ignorent entièrement les drapeaux. Ne considère pas les préférences d’affichage comme un contrôle qui limite l’enregistrement, l’impression ou la copie. C’est le rôle des bits de permission, que les lecteurs n’honorent encore que de manière coopérative. Voir Chiffrer avec des permissions.

Conformité

Déclaration	Spécification	Article
`DisplayDocTitle` contrôle si la barre de titre de la fenêtre affiche le titre du document.	ISO 32000-2	§12.2
`HideToolbar` demande que la barre d’outils interactive soit masquée.	ISO 32000-2	§12.2
`FitWindow` demande que la fenêtre soit redimensionnée à la taille de la première page.	ISO 32000-2	§12.2

Il s’agit de préférences indicatives. Les articles cités définissent leur signification. Ils n’imposent pas aux lecteurs de les honorer. NextPDF ne revendique pas de conformité globale à ISO 32000-2.