Mengatur preferensi penampil dan mode tampilan

Sekilas pandang

Resep ini mengatur cara pembaca Portable Document Format (PDF) yang sesuai standar menampilkan dokumen Anda saat dibuka. Anda dapat mengatur zoom awal, tata letak halaman, kontrol pada pembaca, ukuran jendela, dan teks pada bilah judul. Bilah judul dapat menampilkan judul dokumen atau nama berkas. Resep ini mengikuti examples/24-viewer-preferences.php.

Instalasi

composer require nextpdf/core:^3

Tinjauan konseptual

Preferensi penampil disimpan di dalam katalog dokumen. Preferensi ini adalah petunjuk bagi pembaca, bukan jaminan. Gunakan tiga flag utama berikut. DisplayDocTitle mengontrol teks bilah judul (ISO 32000-2 §12.2). HideToolbar meminta pembaca untuk menyembunyikan bilah alatnya. FitWindow meminta pembaca untuk menyesuaikan ukuran jendelanya agar pas dengan halaman pertama. setDisplayMode() memasangkan zoom awal dengan tata letak halaman.

Profil ini bersifat structural karena dokumen membawa nilai /ID pada trailer. Tahap pasca-pemrosesan menormalkan nilai tersebut sebelum membandingkan dua eksekusi.

Permukaan API

NextPDF\Core\Concerns\HasViewerPreferences (digabungkan ke dalam Document):

setViewerPreferences(array $prefs): static — flag dengan key seperti HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool), serta 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.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Contoh lengkap di bawah ini mencerminkan examples/24-viewer-preferences.php. Contoh ini membuat dokumen multihalaman agar Anda dapat melihat tata letak dua kolom, lalu menulis output ke NEXTPDF_COOKBOOK_OUTPUT untuk 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";

Keluaran yang diharapkan:

Wrote document with viewer preferences

Kasus tepi & jebakan

Preferensi bersifat anjuran. ISO 32000-2 mendefinisikan preferensi penampil sebagai petunjuk. Pembaca dapat mengabaikan salah satu dari preferensi tersebut. Peramban khususnya cenderung hanya mematuhi sangat sedikit di antaranya. Jangan pernah mengandalkan HideToolbar/HideMenubar sebagai jaminan keamanan atau mode kios.
DisplayDocTitle memerlukan judul. Preferensi ini hanya mengubah perilaku ketika setTitle() menetapkan judul yang tidak kosong. Tanpa judul, pembaca tetap menampilkan nama berkas.
String tata letak harus persis. setDisplayMode() mengharapkan ejaan yang sesuai spesifikasi, seperti TwoColumnLeft, bukan two-column-left. Tata letak yang tidak dikenal akan beralih ke pengaturan baku pembaca.
Zoom numerik adalah string. Gunakan '150' untuk 150 %, bukan bilangan bulat 150.
Halaman tunggal vs. bentangan. TwoPageLeft/TwoPageRight memerlukan pembaca PDF 1.5+. Penampil yang lebih lama akan beralih ke tata letak kolom tunggal.

Kinerja

Mengatur preferensi penampil merupakan konfigurasi katalog dengan waktu konstan dan tidak menambah biaya rendering. Operasi ini tetap jauh di bawah anggaran 1000 ms / 64 MB.

Catatan keamanan

Menyembunyikan bilah alat atau bilah menu hanya bersifat kosmetik. Hal ini tidak membatasi apa yang dapat dilakukan pengguna. Setiap pembaca tetap mempertahankan pintasan keyboard dan aksi klik kanan, dan banyak yang sepenuhnya mengabaikan flag tersebut. Jangan memperlakukan preferensi penampil sebagai kontrol yang membatasi penyimpanan, pencetakan, atau penyalinan. Bit izin menangani permintaan tersebut, dan pembaca pun tetap mematuhinya hanya secara kooperatif. Lihat Enkripsi dengan izin.

Kepatuhan

Pernyataan	Spesifikasi	Klausa
`DisplayDocTitle` mengontrol apakah bilah judul jendela menampilkan judul dokumen.	ISO 32000-2	§12.2
`HideToolbar` meminta agar bilah alat interaktif disembunyikan.	ISO 32000-2	§12.2
`FitWindow` meminta agar ukuran jendela diubah menyesuaikan halaman pertama.	ISO 32000-2	§12.2

Preferensi ini bersifat anjuran. Klausa yang dikutip mendefinisikan maknanya. Klausa tersebut tidak menetapkan kewajiban bagi pembaca untuk mematuhinya. NextPDF tidak menyatakan kepatuhan menyeluruh terhadap ISO 32000-2.