من نموذج قابل للتعبئة إلى سجل مجمَّد: تعبئة AcroForm وتسطيحه

SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7

لمحة سريعة

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

لماذا يهم هذا

الفجوة بين “ما عبّأته” و”ما تراه” هي حيث تنحرف النماذج.

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

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

الخلاصة المختصرة

• AcroForm هو النموذج التفاعلي للمستند: شجرة حقول مصنَّفة مُعلَنة في الفهرس (SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7).
• يُجعَل كل حقل مرئياً بـتعليق أداة — المستطيل على الصفحة الذي تنقر أو تكتب فيه (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5).
• يشحن ⁨NextPDF⁩ بُناةً مصنَّفين لكل عنصر تحكم نموذج غير توقيعي مدعوم — النص، ومربع الاختيار، وزر الراديو، ومربع القائمة، ومربع التحرير والسرد (الاختيار)، وزر الدفع — إضافةً إلى مدير حقول يكتبها كائنات ⁨PDF⁩ صحيحة.
• يقوم التسطيح بعرض قيمة كل حقل في دفق محتوى الصفحة وإزالة النموذج التفاعلي الذي صار زائداً، تاركاً سجلاً مجمَّداً.
• إن طلبت تسطيح مستند بلا صفحات، فلن يدمّر ⁨NextPDF⁩ قيم حقولك بهدوء. بل يحفظ النموذج، وينبّهك، ويتيح لك إضافة صفحة والتسطيح على نحو صحيح.

كيف يتعامل ⁨NextPDF⁩ مع هذا

النموذج الذهني طبقتان. الحقل هو البيانات: اسم، ونوع، وقيمة، ومجموعة أعلام. الأداة هي الصورة: مستطيل على صفحة محددة يتيح للعارض التفاعل مع الحقل (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5). يمكن لحقل واحد أن يظهر حتى عبر عدة أدوات — وهكذا بالضبط تعمل مجموعة راديو، عدة خيارات على الصفحة موصولة بقيمة كامنة واحدة.

يمنح ⁨NextPDF⁩ كل نوع حقل بانيه المصنَّف الخاص، فلا تجمّع قاموساً خاماً يدوياً أبداً. يحمل النوع التفاصيل الصحيحة لـ⁨PDF⁩ نيابةً عنك. يشترك مربع الاختيار وزر الراديو وزر الدفع كلها في نوع النموذج الكامن نفسه في المعيار ويُميَّز بعضها عن بعض بأعلامها؛ يضبط المحرك تلك الأعلام من النوع الذي اخترته، بدلاً من أن يسألك تذكّر أي بِتّ يعني “راديو”. مربع القائمة ومربع التحرير والسرد كلاهما حقلا اختيار؛ ومجدداً، يلتقط الباني الترميز الصحيح. تذكر نوع الحقل مرة واحدة، بالكلمات، فتتبع البايتات.

التسطيح هو النصف الثاني. تُجمِّع أداة التسطيح تعليقات الأدوات بحسب صفحتها المالكة، مستخدمةً مستطيل كل أداة لموضع الوضع على تلك الصفحة، ثم تعرض كل قيمة سلسلة صغيرة من مشغّلات دفق المحتوى — اضبط لوناً، اضبط موضع نص، ارسم المحارف — مُلحَقةً بمحتوى تلك الصفحة الموجود (SpecSpec: ISO 32000-2, §8.4ISO 32000-2 §8.4). تتوقف القيمة عن كونها حقلاً حياً وتصير حبراً مطبوعاً. ولأن النموذج لم يعد يحمل أي حقول تفاعلية، يزيل المحرك بعدئذٍ مدخل AcroForm: لم يبقَ شيء تفاعلي.

1. Declare typed fieldsAdd text, checkbox, radio, choice, and button fields through their typed builders; the engine sets the spec-correct PDF type and flags.
2. Place the widgetsEach field is drawn as a widget annotation — a rectangle on a chosen page that a viewer can type into, tick, or pick from.
3. Collect inputShip it fillable: a reader supplies values, or your code sets them, leaving a filled but still-editable document.
4. Flatten the valuesRender each field's value into the page content stream as graphics; the painted value is now immutable.
5. Drop the interactive formWith every value baked in, remove the AcroForm so nothing remains editable — a frozen record of what was agreed.

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

مثال عملي

نموذج صغير تمثيلي: ابنِ بضعة حقول مصنَّفة، ثم سطّحه في سجل مجمَّد.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();

// Typed builders, called straight on the document. You pick the field
// type by choosing its builder method — textField, checkBox, comboBox —
// and you pass the value to freeze at creation time. The engine writes
// the spec-correct PDF type and flags for you.
$document->textField('full_name', x: 40, y: 700, w: 220, h: 18, default: 'Ada Lovelace');
$document->checkBox('agree_terms', x: 40, y: 660, size: 14, checked: true);
$document->comboBox(
    'plan',
    x: 40,
    y: 620,
    w: 160,
    h: 18,
    items: ['Starter', 'Team', 'Enterprise'],
    selected: 'Team',
);

// Flatten: the values become immutable page graphics and the
// interactive AcroForm is dropped. The result is a frozen record.
$document->flattenForms();

$bytes = $document->getPdfData();

قبل flattenForms()، هذا نموذج قابل للتعبئة. بعده، تُطبَع القيم نفسها في الصفحة ولا يبقى حقل لتغييره. تختار نوع الحقل باختيار دالة بانيه — textField، وcheckBox، وcomboBox — فلا يمكن ترميز نوع خاطئ كسلسلة سائبة: الخطأ المطبعي نداء لدالة غير موجودة، يُلتقَط قبل كتابة أي حقل، لا حقلاً خاطئاً بصمت. هذا هو موقف رفض-التخمين نفسه الذي يتخذه بقية المحرك؛ راجع واجهة برمجية ترفض التخمين.

مفهوم خاطئ شائع

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

الخطأ المرآوي هو تسطيح مسودة لا تزال تحتاج إلى جمع مُدخَلات عليها. بمجرد التسطيح، تختفي الحقول — وهذا هو المقصود كله — فسطّح النسخة التي تعتزم أن تكون نهائية، لا النسخة التي لا تزال تتداولها.

Human-factors note:Human-factors note

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

الحدود والقيود

دعم ⁨NextPDF⁩ للنماذج أساسي كامل: بُناة مصنَّفون لعناصر تحكم الحقول التفاعلية الشائعة، وأداة تسطيح نماذج، ومدير حقول يكتب الحقول كائنات ⁨PDF⁩ صحيحة. تصف هذه الصفحة ذلك السطح الأساسي.

AcroForm fields and flattening — edition availability

Edition	Availability
Core	○ بُناة مصنَّفون لحقول النص، ومربع الاختيار، والراديو، والاختيار (مربع القائمة ومربع التحرير والسرد)، وزر الدفع؛ ووضع الأدوات؛ ومدير حقول؛ وأداة تسطيح نماذج تطبع القيم في رسوميات الصفحة. متاح في كل إصدار.
Pro	○Not in this edition
Enterprise	○Not in this edition

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

التسطيح أيضاً ليس توقيعاً. يجعل المستند غير قابل للتحرير بمعنى العارض العادي، لكنه لا يثبت تعمية مَن أنتجه أو أنه لم يتغير منذئذٍ. حين يجب أن يكون السجل مُثبَتاً أنه الذي اتُّفِق عليه، فسطّح ثم وقّع؛ راجع كيف تستقر التوقيعات داخل ملف ⁨PDF⁩.

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

مستندات ذات صلة

• ما الذي يجعل ملف ⁨PDF⁩ قابلاً للوصول — حقول النموذج الموسومة والأسماء القابلة للوصول، للمرحلة القابلة للتعبئة.
• واجهة برمجية ترفض التخمين — لماذا يكون نوع الحقل تعداداً مصنَّفاً، لا سلسلة على المحرك تفسيرها.
• تشريح ملف ⁨PDF⁩ — أين تستقر فعلاً الفهرس والصفحات والتعليقات التي يُبنَى منها نموذج.
• كيف تستقر التوقيعات داخل ملف ⁨PDF⁩ — كيف تجعل سجلاً مجمَّداً مُثبَتاً أنه الذي اتُّفِق عليه.

مسرد المصطلحات

• AcroForm — النموذج التفاعلي لملف ⁨PDF⁩: شجرة الحقول المصنَّفة المُعلَنة في فهرس المستند التي تجعل الملف قابلاً للتعبئة (SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7).
• الحقل — جانب البيانات من عنصر تحكم نموذج: اسم، ونوع، وقيمة، وأعلام. مستقل عن كيف يبدو على الصفحة.
• تعليق الأداة — المستطيل المرئي القابل للنقر على صفحة الذي يتفاعل العارض من خلاله مع حقل (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5). قد يكون لحقل واحد عدة منها.
• حقل الاختيار — حقل يعرض مجموعة خيارات: يُظهِرها مربع القائمة مفتوحةً، ويُظهِرها مربع التحرير والسرد قائمةً منسدلة. كلاهما نوع حقل ⁨PDF⁩ نفسه.
• التسطيح — عرض القيمة الحالية لكل حقل في الصفحة رسوميات غير قابلة للتغيير وإزالة النموذج التفاعلي، مُنتِجاً سجلاً مجمَّداً.
• السجل المجمَّد — مستند مُسطَّح: يُظهِر شيئاً ثابتاً واحداً في كل عارض ولا تبقى به حقول لتحريرها.