عرض جدول HTML باستخدام NextPDF Connect

لمحة سريعة

اعرض بيانات جدولية مُنظَّمة من سلسلة تمثّل جدول ⁨HTML.⁩ تُنقِّي add_table المُدخَلات عبر قائمة سماح صارمة في ⁨DOMDocument⁩ قبل التخطيط، فيبقى الخرج متسقًا حتى عند تباين ترميز المصدر. استخدم أدوات ⁨Core⁩ التالية: create_pdf، وadd_table، وoutput_pdf. يُخطَّط الجدول كشبكة ⁨row/column⁩ (⁨CSS Tables 3⁩ §3.1).

التثبيت

composer require nextpdf/server

اضبط نقلًا. يجب أن تتضمَّن المُدخَلات جذر <table> مع صفوف <tr> وخلايا <th>/<td>.

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

تفرض add_table قائمة سماح ثابتة للعناصر (table، thead، tbody، tfoot، tr، th، td، caption، b، i، u، strong، em، br، p، span). تُجرَّد كل السمات من كل عنصر — style، class، width، colspan، rowspan، id، وما إلى ذلك. يُستبدَل أي وسم خارج قائمة السماح بمحتواه النصي. يعتمد نص الخلية على حالة الخط النشطة في المستند، والتي تضبطها باستخدام set_font قبل add_table. يُعرَض النص بواسطة مُشغِّلات إظهار النص بترتيب دفق المحتوى (⁨ISO 32000-2⁩ §9.4). محرِّك التخطيط، لا ⁨CSS⁩ المضمَّن، هو ما يحدِّد عرض الأعمدة.

واجهة ⁨API⁩

الأداة	الدور	مستوى الخطورة
`create_pdf`	فتح الجلسة	آمنة
`set_font`	ضبط خط نص الخلية (اختياري، قبل `add_table`)	تنبيه
`add_table`	تنقية الجدول وتخطيطه	تنبيه
`output_pdf`	إخراج ملف ⁨PDF⁩ وإرجاعه	موافقة مطلوبة / مراجعة (⁨base64⁩)

يُعد كتالوج الأدوات المرجع المُعتمَد. تعتمد الأدوات المتاحة لديك على الفئة المُثبَّتة.

نموذج التعليمات البرمجية — بداية سريعة

create_pdf (⁨A4⁩ باتجاه طولي، عنوان) ← document_id.
add_table مع سلسلة <table>...</table> كاملة (صف الترويسة وصفوف البيانات).
output_pdf ← ⁨base64⁩ أو كتابة ملف خاضعة للبوابة عند استخدام file_path.

ينتقل المؤشر إلى أسفل آخر صف معروض، تاركًا مساحة للمحتوى التالي.

نموذج التعليمات البرمجية — الإنتاج

تحقَّق من صحة ترميز ⁨HTML⁩ قبل إرساله. اضبط خط الخلية باستخدام set_font لإخراج حتمي. إذا اعتمدت على الافتراضي، فإن خط الخرج يعتمد على التنفيذ. للتحكم في الأدوات التي يجوز للمضيف استدعاؤها، قيِّد السجل عبر سياسة الأمان.

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

⁨HTML⁩ فارغ أو غير جدولي. تؤدي المُدخَلات التي لا تحتوي على <table> إلى خطأ عدم وجود جدول قابل للعرض.
ترميز مشوَّه. تؤدي الوسوم غير المتوازنة إلى خطأ تحليل، لذا تحقَّق من صحة البنية أولًا.
جدول أعرض من الصفحة. قلِّل الأعمدة، أو اختصر المحتوى، أو بدِّل إلى الاتجاه الأفقي.
تجاوز الصفحة. ينتقل الجدول الطويل إلى صفحة جديدة. افحص position.page في الاستجابة، أو استدعِ add_page مسبقًا.

الأداء

يُعرَض الجدول الصغير ضمن الميزانية، ويكون الخرج بضعة كيلوبايت. ملف التعريف هو structural. تُجرى التنقية في تمريرة واحدة على بنية ⁨DOM⁩ المُحلَّلة.

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

تجريد السمات غير مشروط ولا يمكن تجاوزه. وهو يحمي من حقن الأنماط والبرامج النصية عبر ترميز الخلية. لا يبقى أي ⁨CSS⁩ مضمَّن، ولا معالج أحداث، ولا عنوان ⁨URL⁩ من نوع javascript:. تمثّل قائمة السماح حدود الثقة، لذا لا تعامل الخرج المعروض على أنه إعادة إنتاج وفيّة لتنسيق مصدر اعتباطي.

المطابقة

البيان	المواصفة	البند	⁨reference_id⁩
تُخطَّط الجداول كشبكة خلايا ⁨row/column.⁩	⁨CSS Tables 3⁩	§3.1
يُعرَض النص بواسطة مُشغِّلات النص بترتيب الدفق.	⁨ISO 32000-2⁩	§9.4

السياق التجاري

غير منطبق — كل أداة هنا من فئة ⁨Core.⁩

مقتطف من مصفوفة دعم ⁨CSS⁩ (المُتحقَّق منه فقط)

add_table لا تشغِّل محرِّك ⁨CSS⁩ عامًّا. السلوك الوحيد المرتبط بـ “⁨CSS⁩” هو نموذج شبكة الجدول الثابت: تأتي الصفوف والأعمدة من بنية الجدول، ويختار محرِّك التخطيط العروض. التنسيق المضمَّن غير مدعوم بحكم التصميم لأن السمات تُجرَّد. للاطلاع على تغطية ⁨CSS⁩ على مستوى المحرِّك (غير الخاص بـ ⁨Connect⁩)، راجع مصفوفة دعم ⁨CSS⁩ للمشروع.

قيد التدفق أحادي التمريرة

تُحلِّل add_table الترميز المُقدَّم إلى ⁨DOM⁩ مرة واحدة ثم تخطِّطه في تمريرة واحدة. وهي لا تعيد التدفق استنادًا إلى أوراق أنماط خارجية. الجدول الذي يتجاوز الصفحة ينتقل إلى الصفحة التالية بدلًا من إعادة التدفق بأثر رجعي.

ميزانية الذاكرة للجداول الكبيرة

تحتفظ الجداول الكبيرة جدًّا بـ ⁨DOM⁩ المُحلَّل والخلايا المُخطَّطة في الذاكرة طوال مدة الاستدعاء. قسِّم مجموعات البيانات الكبيرة عبر استدعاءات add_table متعددة لتبقى ضمن ميزانية الذاكرة القصوى.

توافر النقل

النقل	متاح	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم	ترميز ⁨HTML⁩ الكبير يزيد حجم إطار ⁨stdio.⁩
⁨REST⁩	نعم	أرسل ترميز ⁨HTML⁩ في نص الطلب.
⁨gRPC⁩	نعم	أحادي؛ تنطبق حدود حجم الرسالة.

مستوى خطورة ⁨HITL⁩

create_pdf آمنة؛ وset_font وadd_table تتطلَّبان تنبيهًا؛ وoutput_pdf تتطلَّب موافقة تنخفض إلى مراجعة في وضع ⁨base64.⁩ يبقى إخراج الملف يتطلَّب موافقة. راجع ⁨output-approval⁩.

غلاف ⁨JSON⁩ لبوابة التأكيد

إخراج ⁨base64⁩:

{ "allowed": true }

يعيد إخراج الملف غلاف التحدي الذي يوثِّقه ⁨output-approval⁩.