Anzeigeeinstellungen und Anzeigemodus festlegen

Auf einen Blick

Mit diesem Recipe konfigurieren Sie, wie ein konformer PDF-Reader Ihr Dokument beim Öffnen darstellt. Sie legen den anfänglichen Zoom, das Seitenlayout, die Sichtbarkeit der Reader-Bedienelemente, die Fenstergröße und den Text in der Titelleiste fest. Die Titelleiste kann den Dokumenttitel oder den Dateinamen anzeigen. Das Recipe folgt examples/24-viewer-preferences.php.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Die Anzeigeeinstellungen befinden sich im Dokumentkatalog. Sie sind Hinweise für den Reader, keine Garantien. Die drei wichtigsten Flags verhalten sich wie folgt. DisplayDocTitle steuert den Text in der Titelleiste (ISO 32000-2 §12.2). HideToolbar fordert an, die Symbolleiste des Readers auszublenden. FitWindow bittet den Reader, sein Fenster an die erste Seite anzupassen. setDisplayMode() kombiniert den anfänglichen Zoom mit einem Seitenlayout.

Das Profil ist structural, weil das Dokument im Trailer einen /ID-Wert trägt. Die Nachbearbeitung normalisiert diesen Wert, bevor sie zwei Durchläufe vergleicht.

API-Oberfläche

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

setViewerPreferences(array $prefs): static — Flags mit Schlüsseln wie HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool) sowie 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.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

Das vollständige Beispiel unten entspricht examples/24-viewer-preferences.php. Es erzeugt ein mehrseitiges Dokument, damit das zweispaltige Layout sichtbar wird, und schreibt die Ausgabe für den Harness nach NEXTPDF_COOKBOOK_OUTPUT.

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

Erwartete Ausgabe:

Wrote document with viewer preferences

Sonderfälle & Fallstricke

Einstellungen sind beratend. ISO 32000-2 definiert Anzeigeeinstellungen als Hinweise. Reader dürfen jede davon ignorieren. Browser berücksichtigen insbesondere nur sehr wenige davon. Verlassen Sie sich niemals auf HideToolbar/HideMenubar als Sicherheits- oder Kiosk-Garantie.
DisplayDocTitle braucht einen Titel. Diese Einstellung ändert das Verhalten nur, wenn setTitle() einen nicht leeren Titel gesetzt hat. Ohne Titel zeigt der Reader ohnehin den Dateinamen an.
Layout-Strings sind exakt. setDisplayMode() erwartet die Schreibweisen aus der Spezifikation, etwa TwoColumnLeft, nicht two-column-left. Ein unbekanntes Layout fällt auf den Reader-Standard zurück.
Numerischer Zoom ist ein String. Geben Sie '150' für 150 % an, nicht den Integer 150.
Einzelseite vs. Doppelseite. TwoPageLeft/TwoPageRight erfordern PDF 1.5+-Reader. Ältere Viewer fallen auf ein einspaltiges Layout zurück.

Performance

Das Setzen der Anzeigeeinstellungen konfiguriert den Katalog in konstanter Zeit und verursacht keine Rendering-Kosten. Es bleibt deutlich innerhalb des Budgets von 1000 ms / 64 MB.

Sicherheitshinweise

Das Ausblenden der Symbolleiste oder der Menüleiste ist rein kosmetisch. Es schränkt nicht ein, was Benutzer tun können. Jeder Reader behält Tastenkürzel und Rechtsklick-Aktionen, und viele ignorieren die Flags vollständig. Behandeln Sie Anzeigeeinstellungen nicht als Steuerung, die das Speichern, Drucken oder Kopieren einschränkt. Diese Aufgabe übernehmen die Berechtigungs-Bits, die Reader allerdings ebenfalls nur kooperativ beachten. Siehe Mit Berechtigungen verschlüsseln.

Konformität

Aussage	Spezifikation	Abschnitt
`DisplayDocTitle` steuert, ob die Titelleiste des Fensters den Dokumenttitel anzeigt.	ISO 32000-2	§12.2
`HideToolbar` fordert an, dass die interaktive Symbolleiste ausgeblendet wird.	ISO 32000-2	§12.2
`FitWindow` fordert an, dass das Fenster an die erste Seite angepasst wird.	ISO 32000-2	§12.2

Es handelt sich um beratende Einstellungen. Die zitierten Klauseln definieren ihre Bedeutung. Sie begründen keine Pflicht eines Readers, sie zu beachten. NextPDF erhebt keinen pauschalen Anspruch auf ISO 32000-2-Konformität.