Ustawianie preferencji przeglądarki i trybu wyświetlania

W skrócie

Ten przepis pokazuje, jak kontrolować sposób, w jaki zgodna ze specyfikacją przeglądarka dokumentów Portable Document Format (PDF) prezentuje dokument podczas otwierania. Pozwala ustawić początkowe powiększenie, układ strony, elementy sterujące przeglądarki, rozmiar okna oraz tekst paska tytułu. Pasek tytułu może wyświetlać tytuł dokumentu albo nazwę pliku. Przepis jest oparty na examples/24-viewer-preferences.php.

Instalacja

composer require nextpdf/core:^3

Omówienie koncepcyjne

Preferencje przeglądarki znajdują się w katalogu dokumentu. Są wskazówkami dla przeglądarki, a nie gwarancjami. Trzy główne flagi działają następująco. DisplayDocTitle kontroluje tekst paska tytułu (ISO 32000-2 §12.2). HideToolbar żąda ukrycia paska narzędzi przeglądarki. FitWindow żąda zmiany rozmiaru okna tak, aby mieściła się w nim pierwsza strona. setDisplayMode() łączy początkowe powiększenie z układem strony.

Profil ma wartość structural, ponieważ dokument zawiera wartość /ID w zwiastunie. Przebieg końcowy normalizuje tę wartość przed porównaniem dwóch uruchomień.

Interfejs API

NextPDF\Core\Concerns\HasViewerPreferences (włączona do Document):

setViewerPreferences(array $prefs): static — flagi o kluczach takich jak HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool), oraz 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.

Przykładowy kod — szybki start

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

Przykładowy kod — produkcja

Pełny przykład poniżej odzwierciedla examples/24-viewer-preferences.php. Tworzy dokument wielostronicowy, dzięki czemu można zobaczyć układ dwukolumnowy, i zapisuje go do NEXTPDF_COOKBOOK_OUTPUT na potrzeby mechanizmu testowego.

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

Oczekiwany wynik:

Wrote document with viewer preferences

Przypadki brzegowe i pułapki

Preferencje mają charakter doradczy. ISO 32000-2 definiuje preferencje przeglądarki jako wskazówki. Przeglądarki mogą zignorować dowolną z nich. Dotyczy to zwłaszcza przeglądarek internetowych, które respektują bardzo niewiele takich ustawień. Nigdy nie polegaj na HideToolbar/HideMenubar jako gwarancji bezpieczeństwa ani trybu kiosku.
DisplayDocTitle wymaga tytułu. Zmienia działanie tylko wtedy, gdy setTitle() ustawi niepusty tytuł. Bez tytułu przeglądarka nadal wyświetla nazwę pliku.
Ciągi znaków układu muszą być dokładne. setDisplayMode() oczekuje pisowni ze specyfikacji, takiej jak TwoColumnLeft, a nie two-column-left. Nieznany układ powoduje powrót do domyślnego ustawienia przeglądarki.
Powiększenie liczbowe jest ciągiem znaków. Przekaż '150' dla 150 %, a nie liczbę całkowitą 150.
Pojedyncza strona a rozkładówka. TwoPageLeft/TwoPageRight wymagają przeglądarek obsługujących PDF 1.5+. Starsze przeglądarki wracają do układu jednokolumnowego.

Wydajność

Ustawianie preferencji przeglądarki to konfiguracja katalogu wykonywana w stałym czasie, bez żadnego kosztu renderowania. Mieści się z dużym zapasem w budżecie 1000 ms / 64 MB.

Uwagi dotyczące bezpieczeństwa

Ukrycie paska narzędzi lub paska menu ma charakter wyłącznie kosmetyczny. Nie ogranicza tego, co może zrobić użytkownik. Każda przeglądarka zachowuje skróty klawiaturowe oraz działania menu kontekstowego, a wiele z nich całkowicie ignoruje te flagi. Nie traktuj preferencji przeglądarki jako mechanizmu ograniczającego zapisywanie, drukowanie lub kopiowanie. Takimi ograniczeniami zarządzają bity uprawnień, a przeglądarki nadal respektują je wyłącznie na zasadzie współpracy. Zobacz Szyfrowanie z uprawnieniami.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
`DisplayDocTitle` kontroluje, czy pasek tytułu okna wyświetla tytuł dokumentu.	ISO 32000-2	§12.2
`HideToolbar` żąda ukrycia interaktywnego paska narzędzi.	ISO 32000-2	§12.2
`FitWindow` żąda zmiany rozmiaru okna do rozmiaru pierwszej strony.	ISO 32000-2	§12.2

Te preferencje mają charakter doradczy. Przytoczone klauzule definiują ich znaczenie. Nie nakładają na przeglądarkę obowiązku ich respektowania. NextPDF nie zapewnia całościowej zgodności z ISO 32000-2.