تسطيح حقول النموذج إلى محتوى ثابت على الصفحة

لمحة سريعة

استخدم هذه الوصفة لتسطيح نموذج ⁨AcroForm⁩ تفاعلي. يرسم ⁨NextPDF⁩ القيمة الحالية لكل حقل ضمن دفق محتوى الصفحة كرسوميات عادية، ثم يزيل قاموس ⁨AcroForm⁩. والنتيجة نموذج غير تفاعلي: تمثيل ثابت للحقول يظهر بالطريقة نفسها في كل مكان، حتى عند فتحه في قارئ لا يدعم النماذج (⁨ISO 32000-2⁩ §12.7). تبني الوصفة النموذج من examples/30-form-fields.php، ثم تستدعي flattenForms().

التثبيت

composer require nextpdf/core:^3

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

يعامل التسطيح كل عنصر كما لو أنه مطبوع على صفحته. تتحول الحقول النصية إلى نص من النوع BT … Tj … ET. وتتحول مربعات الاختيار وأزرار الانتقاء إلى مسارات مرسومة. وتعرض حقول الاختيار العنصر المحدد فيها. وتظهر أزرار الضغط على هيئة مربع ثابت يشبه الزر. يتوافق ذلك مع ما تصفه المواصفة لمظهر معرَّف تعريفًا ثابتًا عندما تكون محتويات الحقل معروفة مسبقًا (⁨ISO 32000-2⁩ §12.7). ولأن ⁨NextPDF⁩ يثبّت القيم داخل الصفحة، فإن آلية NeedAppearances المهملة لا تعود لازمة.

ملف تعريف قابلية إعادة الإنتاج هو structural. يتضمن المستند مُدخل /ID في ذيل الملف، وتوحّده مرحلة لاحقة قبل مقارنة تشغيلين.

واجهة ⁨API⁩

NextPDF\Core\Concerns\HasFormFields::flattenForms(): static يسطّح كل حقل أُنشئ في المستند إلى محتوى ثابت على الصفحة ويزيل قاموس ⁨AcroForm⁩. إذا لم توجد حقول، فلا يفعل شيئًا. داخليًا، يفوّض العمل إلى NextPDF\Form\FormFlattener.

ابنِ النموذج باستخدام مُنشئات الحقول. لمعرفة الخطوات التفصيلية، راجع بناء نموذج ⁨PDF⁩ وتعبئته مسبقًا. ثم استدعِ flattenForms() قبل save().

مثال برمجي — بداية سريعة

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Flattened Form');
$doc->addPage();

$doc->textField(name: 'full_name', x: 20, y: 30, w: 90, h: 8, default: 'Ada Lovelace');
$doc->checkBox(name: 'agree', x: 20, y: 45, size: 5, checked: true);

// Bake the field values into the page; the AcroForm is removed.
$doc->flattenForms();

$doc->save(__DIR__ . '/flattened.pdf');
echo "Wrote flattened.pdf (no interactive fields)\n";

مثال برمجي — إنتاجي

يبني المثال الكامل أدناه نموذجًا متعدد الأقسام من examples/30-form-fields.php. يملأه مسبقًا، ويسطّحه، ويكتب الناتج إلى NEXTPDF_COOKBOOK_OUTPUT من أجل بيئة الاختبار.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Customer Registration — Flattened');
$doc->addPage();

$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Customer Registration (read-only copy)', newLine: true);
$doc->ln(4);

$leftMargin = 15.0;
$fieldX     = 70.0;
$fieldW     = 120.0;
$fieldH     = 8.0;
$rowSpacing = 12.0;

$prefill = [
    'full_name' => 'Ada Lovelace',
    'email'     => '[email protected]',
    'phone'     => '+44 20 7946 0000',
    'company'   => 'Analytical Engines Ltd',
];

$y = 40.0;
$doc->setFont('helvetica', '', 10);
foreach ($prefill as $name => $value) {
    $doc->setXY($leftMargin, $y);
    $doc->cell(50, $fieldH, ucwords(str_replace('_', ' ', $name)) . ':');
    $doc->textField(name: $name, x: $fieldX, y: $y, w: $fieldW, h: $fieldH, default: $value);
    $y += $rowSpacing;
}

$y += 6;
$doc->setXY($leftMargin, $y);
$doc->cell(0, 7, 'Newsletter');
$doc->checkBox(name: 'newsletter', x: $leftMargin + 70, y: $y, size: 5, checked: true);

// Flatten: widgets become static page content; the AcroForm is dropped.
$doc->flattenForms();

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/registration-flattened.pdf');

echo "Wrote flattened registration form\n";

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

Wrote flattened registration form

يعرض المستند الناتج القيم نفسها، من دون أي حقول تفاعلية. ويظهر بالطريقة نفسها في قارئ لا يدعم النماذج.

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

• التسطيح غير قابل للتراجع. بمجرد استدعاء save()، تختفي الحقول التفاعلية. احتفظ بالمصدر غير المسطَّح إذا كان من المحتمل أن تحتاج إلى تحرير القيم لاحقًا.
• ترتيب الاستدعاء. شغّل flattenForms() بعد إنشاء الحقول وقبل save(). استدعاؤه دون وجود حقول لا يفعل شيئًا، وهو آمن.
• حقول التوقيع لا تُسطَّح. المظهر المرئي لحقل /Sig هو المظهر الناتج عن ‏⁨CMS⁩‏ (⁨Cryptographic Message Syntax⁩) ⁨SignedData⁩ الخاصة به، وليس قيمة قابلة لإعادة العرض. وإعادة تنقيطه ستنشئ رسمًا “شبحيًا” ثابتًا لم يعد يطابق أي توقيع قابل للتحقق. ولهذا السبب، يتخطى المُسطِّح حقول التوقيع عن قصد. سطّح النموذج قبل التوقيع، ولا تفعل ذلك بعده أبدًا.
• القيمة المنطقية لمربع الاختيار. يعرض مربع الاختيار علامة التحديد عندما تكون قيمته Yes/On/1/true. أما القيمة الفارغة أو Off فتعرض المربع فقط.
• خط النص المسطَّح. يستخدم النص المسطَّح الخط الحالي. وعند عدم تعيين خط، يستخدم ⁨Helvetica⁩ افتراضيًا. أما قيم الحقول بالصينية واليابانية والكورية (⁨CJK⁩) أو بخط مخصص، فعيّن الخط المطلوب قبل flattenForms().

الأداء

يتوسّع التسطيح خطيًا مع عدد الحقول. لكل حقل، يُلحق ⁨NextPDF⁩ كتلة محتوى محدودة، ثم يزيل كائن ⁨AcroForm⁩. تبقى النماذج المعتادة ضمن ميزانية 1500 ⁨ms⁩ / 64 ⁨MB⁩ بهامش مريح.

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

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

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
النموذج المسطَّح هو تمثيل غير تفاعلي (ثابت) للحقول.	⁨ISO 32000-2⁩	§12.7
يُعرَّف مظهر الحقل تعريفًا ثابتًا عندما تكون محتوياته معروفة مسبقًا.	⁨ISO 32000-2⁩	§12.7
المظاهر المثبَّتة داخل الصفحة تجعل راية NeedAppearances المهملة غير لازمة.	⁨ISO 32000-2⁩	§12.7

يُنتج ⁨NextPDF⁩ البنية الثابتة الموصوفة في البنود المذكورة. ولا يدّعي مطابقة شاملة لـ⁨ISO 32000-2⁩.

انظر أيضًا

• وحدة النماذج
• بناء نموذج ⁨PDF⁩ وتعبئته مسبقًا
• التشفير مع الأذونات