Viewervoorkeuren en weergavemodus instellen

In een oogopslag

Met dit recipe bepaal je hoe een conforme Portable Document Format (PDF)-lezer je document presenteert wanneer het wordt geopend. Je stelt de initiële zoom, de pagina-lay-out, de lezerbedieningen, de venstergrootte en de tekst in de titelbalk in. De titelbalk kan de documenttitel of de bestandsnaam tonen. Dit recipe volgt examples/24-viewer-preferences.php.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Viewervoorkeuren staan in de documentcatalogus. Het zijn aanwijzingen voor de lezer, geen garanties. Zo gebruik je de drie belangrijkste vlaggen. DisplayDocTitle bepaalt welke tekst in de titelbalk staat (ISO 32000-2 §12.2). HideToolbar verzoekt de lezer de werkbalk te verbergen. FitWindow verzoekt de lezer de venstergrootte aan te passen aan de eerste pagina. setDisplayMode() koppelt een initiële zoom aan een pagina-lay-out.

Het profiel is structural omdat het document een trailer-/ID-waarde bevat. De nabewerkingsstap normaliseert die waarde voordat twee runs met elkaar worden vergeleken.

API-oppervlak

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

• setViewerPreferences(array $prefs): static — vlaggen met sleutels zoals HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool), plus 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.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

Het volledige voorbeeld hieronder komt overeen met examples/24-viewer-preferences.php. Het maakt een document met meerdere pagina’s, zodat je de lay-out met twee kolommen kunt zien, en schrijft naar NEXTPDF_COOKBOOK_OUTPUT voor het testharnas.

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

Verwachte uitvoer:

Wrote document with viewer preferences

Randgevallen en valkuilen

• Voorkeuren zijn adviserend. ISO 32000-2 definieert viewervoorkeuren als aanwijzingen. Lezers kunnen ze afzonderlijk negeren. Vooral browsers respecteren er maar heel weinig. Vertrouw nooit op HideToolbar/HideMenubar voor een beveiligings- of kioskgarantie.
• DisplayDocTitle heeft een titel nodig. Deze vlag wijzigt het gedrag alleen wanneer setTitle() een niet-lege titel instelt. Zonder titel toont de lezer nog steeds de bestandsnaam.
• Lay-outstrings zijn exact. setDisplayMode() verwacht de exacte spellingen uit de specificatie, zoals TwoColumnLeft, niet two-column-left. Een onbekende lay-out valt terug op de standaardinstelling van de lezer.
• Een numerieke zoom is een string. Geef '150' door voor 150 %, niet het gehele getal 150.
• Eén pagina versus spread. TwoPageLeft/TwoPageRight vereisen lezers met PDF 1.5+. Oudere viewers vallen terug op een lay-out met één kolom.

Prestaties

Het instellen van viewervoorkeuren is catalogusconfiguratie met constante tijdscomplexiteit en heeft geen invloed op de renderingprestaties. Het blijft ruim binnen het budget van 1000 ms / 64 MB.

Beveiligingsnotities

Het verbergen van de werkbalk of menubalk is cosmetisch. Het beperkt niet wat de gebruiker kan doen. Lezers kunnen sneltoetsen en rechtsklikacties blijven aanbieden, en veel lezers negeren de vlaggen volledig. Beschouw viewervoorkeuren niet als een mechanisme dat opslaan, afdrukken of kopiëren beperkt. Permission-bits regelen zulke verzoeken, en ook die respecteren lezers alleen op coöperatieve basis. Zie Versleutelen met permissies.

Conformiteit

Verklaring	Specificatie	Clausule	reference_id
DisplayDocTitle bepaalt of de titelbalk van het venster de documenttitel toont.	ISO 32000-2	§12.2
HideToolbar verzoekt de lezer de interactieve werkbalk te verbergen.	ISO 32000-2	§12.2
FitWindow verzoekt de lezer de venstergrootte aan de eerste pagina aan te passen.	ISO 32000-2	§12.2

Deze voorkeuren zijn adviserend. De aangehaalde clausules definiëren hun betekenis. Ze leggen een lezer niet op om ze te respecteren. NextPDF claimt geen algehele ISO 32000-2-conformiteit.

Zie ook

• Document-module
• Documentmetadata instellen
• Document met meerdere pagina’s