إنشاء نموذج PDF وتعبئته مسبقًا

نظرة سريعة

نموذج ⁨AcroForm⁩ هو نموذج تفاعلي داخل ملف ⁨PDF.⁩ في هذه الوصفة، تنشئ نموذج ⁨AcroForm⁩ وتعبّئ حقوله مسبقًا بقيم ابتدائية. سمة HasFormFields في ⁨Core⁩ هي واجهة برمجية لتأليف النماذج: تنشئ كل حقل وتزوّده بقيمته في الاستدعاء نفسه. استخدم الوسيط default للحقول النصية، وselected لحقول الاختيار، وchecked لمربعات الاختيار. عند فتح ملف ⁨PDF⁩، تظهر حقوله معبّأة مسبقًا وتبقى قابلة للتحرير في أي قارئ متوافق؛ لذلك يستطيع أي شخص يفتح الملف تغييرها. تستند هذه الوصفة إلى examples/30-form-fields.php.

حدود النطاق. ينشئ ⁨Core⁩ حقول النموذج ويعبّئها أثناء إنشاء المستند. وهو لا يقرأ نموذجًا موجودًا مسبقًا في ملف ⁨PDF⁩ من طرف ثالث، ولا يدمج فيه خريطة قيم. وفي هذه الوصفة تعني “التعبئة” تأليف النموذج مع قيمه، لا تحميل ملف ⁨PDF⁩ خارجي وتعبئته. أما استرجاع نموذج خارجي وإعادة كتابته فهو قدرة من قدرات ⁨Premium⁩ والخادم، وليس واجهة برمجية عامة في ⁨Core.⁩

التثبيت

composer require nextpdf/core:^3

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

يخزّن حقل ⁨AcroForm⁩ قيمته الحالية في مدخل V داخل قاموس الحقل (⁨ISO 32000-2⁩ §12.7). ويمكنه أيضًا حفظ قيمة افتراضية اختيارية في DV يرجع إليها الحقل عند تنفيذ إجراء إعادة ضبط النموذج. يضبط ⁨NextPDF⁩ قيمة V من القيمة التي تمرّرها إلى مُنشئ كل حقل. ويستخدم عرض النص سلسلة المظهر الافتراضية (DA).

ملف التعريف هو structural لأن المستند يتضمّن مصفوفة /ID في المقطورة. وتوحّد تمريرة لاحقة هذا المعرّف المتغيّر قبل المقارنة.

واجهة ⁨API⁩

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

• textField(string $name, float $x, float $y, float $w, float $h, string $default = '', array $options = []): static
• checkBox(string $name, float $x, float $y, float $size, bool $checked = false): static
• radioButton(string $name, float $x, float $y, float $size, string $value, string $group): static
• comboBox(string $name, float $x, float $y, float $w, float $h, array $items, string $selected = ''): static
• listBox(string $name, float $x, float $y, float $w, float $h, array $items, string $selected = ''): static
• button(string $name, float $x, float $y, float $w, float $h, string $caption, string $action = ''): static

تحمل الوسائط default وchecked وselected قيم التعبئة المسبقة.

مثال على الشيفرة — بداية سريعة

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

// Text field pre-filled with a value (sets the field dictionary /V entry).
$doc->textField(name: 'full_name', x: 20, y: 30, w: 90, h: 8, default: 'Ada Lovelace');

// Choice field pre-selected.
$doc->comboBox(
    name: 'country',
    x: 20, y: 45, w: 90, h: 8,
    items: ['United Kingdom', 'Taiwan', 'Japan'],
    selected: 'Taiwan',
);

// Checkbox pre-checked.
$doc->checkBox(name: 'newsletter', x: 20, y: 60, size: 5, checked: true);

$doc->save(__DIR__ . '/prefilled-form.pdf');
echo "Wrote prefilled-form.pdf\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 — Pre-filled');
$doc->addPage();

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

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

// --- Personal information, pre-filled ---
$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,
        options: ['maxLen' => 80],
    );
    $y += $rowSpacing;
}

// --- Choice field, pre-selected ---
$y += 6;
$doc->setXY($leftMargin, $y);
$doc->cell(50, $fieldH, 'Country:');
$doc->comboBox(
    name: 'country',
    x: $fieldX,
    y: $y,
    w: $fieldW,
    h: $fieldH,
    items: ['United States', 'United Kingdom', 'Germany', 'Japan', 'Taiwan'],
    selected: 'United Kingdom',
);

// --- Checkboxes, pre-set ---
$y += $rowSpacing + 6;
$doc->setXY($leftMargin, $y);
$doc->cell(0, 7, 'Subscribe to newsletter');
$doc->checkBox(name: 'newsletter', x: $leftMargin + 70, y: $y, size: 5, checked: true);

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

echo "Wrote pre-filled registration form\n";

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

Wrote pre-filled registration form

عند فتح ملف ⁨PDF⁩، يظهر كل حقل معبّأً مسبقًا ويظل قابلًا للتحرير.

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

• يجب أن تكون أسماء الحقول فريدة. إذا تشارك حقلان الاسم نفسه، يصبحان حقلًا منطقيًا واحدًا بقيمة مشتركة في القرّاء المتوافقين. وهذا مفيد للحقول المرتبطة، لكنه مفاجئ في غير ذلك.
• دلالات مجموعة أزرار الاختيار. يربط radioButton() كل خيار بمجموعة group. والخيار المحدد هو الخيار الذي تتطابق قيمة value الخاصة به مع قيمة المجموعة. يكون خيار واحد فقط مفعّلًا في كل مجموعة في الوقت نفسه.
• maxLen هو تلميح. يحدّ خيار maxLen من طول الإدخال في القرّاء المتوافقين. ولا يحدّ من القيمة المخزّنة التي تعبّئها مسبقًا.
• الإحداثيات في الواجهة البرمجية تبدأ من الزاوية العليا اليسرى. تتولى السمة تحويلها إلى نقطة أصل ⁨PDF⁩ في الزاوية السفلى اليسرى نيابة عنك؛ لذا مرّر إحداثيات الزاوية العليا اليسرى كما يوضّح المثال.
• لا تعبئة لملفات ⁨PDF⁩ خارجية. لا توجد طريقة في ⁨Core⁩ تحمّل نموذجًا قائمًا من طرف ثالث وتطبّق عليه خريطة قيم. راجع حدود النطاق أعلاه.

الأداء

يتدرّج تأليف النموذج خطيًا مع عدد الحقول. يضيف كل حقل تعليق أداة واحدًا ومظهرًا واحدًا. وتبقى بضع مئات من الحقول ضمن ميزانية 1500 ⁨ms⁩ / 64 ⁨MB⁩ بهامش مريح.

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

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

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
تُخزَّن قيمة الحقل الحالية في مدخل V ضمن قاموس الحقل.	⁨ISO 32000-2⁩	§12.7
تُخزَّن القيمة الافتراضية في مدخل DV وتُستعاد عند إعادة ضبط النموذج.	⁨ISO 32000-2⁩	§12.7
يستخدم تنسيق نص الحقل سلسلة المظهر الافتراضية DA.	⁨ISO 32000-2⁩	§12.7

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

انظر أيضًا

• وحدة النماذج
• تسطيح حقول النموذج
• التشفير مع الأذونات