اضبط تفضيلات العارض ووضع العرض

لمحة سريعة

توضح هذه الوصفة كيفية تحكمك في طريقة عرض قارئ ⁨Portable Document Format⁩ ‏(⁨PDF⁩) متوافق لمستندك عند فتحه. فهي تضبط مستوى التكبير الأولي، وتخطيط الصفحة، وعناصر تحكم القارئ، وحجم النافذة، ونص شريط العنوان. يمكن أن يعرض شريط العنوان عنوان المستند أو اسم الملف. تتبع هذه الوصفة examples/24-viewer-preferences.php.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية عامة

توجد تفضيلات العارض في كتالوج المستند. وهي تلميحات للقارئ، لا ضمانات. استخدم الأعلام الرئيسية الثلاثة على النحو الآتي. يتحكم DisplayDocTitle في نص شريط العنوان (⁨ISO 32000-2⁩ §12.2). يطلب HideToolbar من القارئ إخفاء شريط أدواته. يطلب FitWindow من القارئ تغيير حجم نافذته لتلائم الصفحة الأولى. يقرن setDisplayMode() مستوى تكبير أوليًا بتخطيط صفحة.

يكون ملف التعريف structural لأن المستند يحمل قيمة /ID في المقطورة. وتسوّي خطوة المعالجة اللاحقة تلك القيمة قبل المقارنة بين تشغيلين.

واجهة برمجة التطبيقات (⁨API⁩)

NextPDF\Core\Concerns\HasViewerPreferences (مدمجة في Document):

• setViewerPreferences(array $prefs): static — أعلام مفاتيح مثل HideToolbar، HideMenubar، HideWindowUI، FitWindow، CenterWindow، DisplayDocTitle (⁨bool⁩)، بالإضافة إلى 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.

عينة الشيفرة — بداية سريعة

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

عينة الشيفرة — إنتاج

يعكس المثال الكامل أدناه examples/24-viewer-preferences.php. ينشئ المثال مستندًا متعدد الصفحات حتى تتمكن من رؤية تخطيط العمودين، ويكتب إلى 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";

الخرج المتوقع:

Wrote document with viewer preferences

الحالات الحدّية والمزالق

• التفضيلات استشارية. يعرّف ⁨ISO 32000-2⁩ تفضيلات العارض بوصفها تلميحات. وقد يتجاهل القُرّاء أيًّا منها. وتحترم المتصفحات خصوصًا قدرًا محدودًا جدًا منها. لا تعتمد أبدًا على HideToolbar/HideMenubar كضمان أمني أو كضمان لوضع الكشك.
• DisplayDocTitle يحتاج إلى عنوان. لا يغيّر السلوك إلا عندما يضبط setTitle() عنوانًا غير فارغ. ومن دون عنوان، يظل القارئ يعرض اسم الملف.
• سلاسل التخطيط دقيقة تمامًا. يتوقع setDisplayMode() تهجئة المواصفة، مثل TwoColumnLeft، لا two-column-left. ويعود التخطيط غير المعروف إلى الإعداد الافتراضي للقارئ.
• التكبير الرقمي سلسلة نصية. مرّر '150' من أجل 150 %، وليس العدد الصحيح 150.
• صفحة واحدة مقابل العرض المزدوج. يتطلب TwoPageLeft/TwoPageRight قُرّاء ⁨PDF 1.5⁩+. وتعود القُرّاء الأقدم إلى تخطيط بعمود واحد.

الأداء

ضبط تفضيلات العارض هو تكوين للكتالوج بزمن ثابت، ولا يضيف تكلفة إلى العرض. ويبقى ضمن ميزانية 1000 ⁨ms⁩ / 64 ⁨MB⁩ بهامش واسع.

ملاحظات أمنية

إخفاء شريط الأدوات أو شريط القوائم إجراء تجميلي. فهو لا يقيّد ما يمكن للمستخدم فعله. يحتفظ كل قارئ باختصارات لوحة المفاتيح وإجراءات النقر بالزر الأيمن، ويتجاهل كثيرون الأعلام تمامًا. لا تعامل تفضيلات العارض على أنها عنصر تحكم يقيّد الحفظ أو الطباعة أو النسخ. تعالج بتات الأذونات تلك الطلبات، ومع ذلك لا يحترمها القُرّاء إلا تعاونيًا. انظر التشفير مع الأذونات.

المطابقة

البيان	المواصفة	البند	⁨reference_id⁩
DisplayDocTitle يتحكم في ما إذا كان شريط عنوان النافذة يعرض عنوان المستند.	⁨ISO 32000-2⁩	§12.2
HideToolbar يطلب إخفاء شريط الأدوات التفاعلي.	⁨ISO 32000-2⁩	§12.2
FitWindow يطلب تغيير حجم النافذة لتلائم الصفحة الأولى.	⁨ISO 32000-2⁩	§12.2

هذه التفضيلات استشارية. وتحدّد البنود المستشهد بها معناها، لكنها لا تحدّد التزام القارئ باحترامها. لا تؤكّد ⁨NextPDF⁩ المطابقة الشاملة لـ ⁨ISO 32000-2.⁩

انظر أيضًا

• وحدة ⁨Document⁩
• ضبط بيانات المستند الوصفية
• مستند متعدد الصفحات