منشئ بيانات الجدول

افتح المنشئ

حدد جدولًا في مساحة العمل. اختر فتح منشئ البيانات في تبويب البيانات بلوحة الفحص. تفصل تبويبات الحقول والمصدر والمعاينة بنية الجدول عن بياناته.

الأعمدة وصفوف الملخص

أضف أعمدة في «الحقول» وحدد عنوان كل منها وحقل بياناته. اضبط العرض والتنسيق والمظهر المتقدم حسب الحاجة. يمكنك إضافة صفوف إجمالي أو إجمالي فرعي أو ملاحظة أسفل الجدول؛ ويشرح قسم المجاميع حسابها.

المجاميع

اختر حسابًا لصف الإجمالي أو الإجمالي الفرعي: مجموع أو متوسط أو قيمة دنيا أو قصوى أو عدّ الصفوف. تُكتب النتيجة في عمود القيمة وتُحسب من جميع صفوفه؛ ويُستخدم تنسيق العمود ما لم يكن للصف تنسيق خاص.

"summaryRows": [
  { "type": "total", "label": "الإجمالي الكلي",
    "aggregate": "sum", "targetColumnKey": "total" }
]

تُحسب فقط الخلايا التي تصل كأعداد؛ تُتجاوز الخلايا الفارغة ويترك مبلغ مُرسل كنص («1,250.00») النتيجة فارغة. يشمل الإجمالي الفرعي جميع الصفوف أيضًا، لا كل صفحة. عند اختيار حقل بيانات يقرأ مربع القيمة من جذر بياناتك لا من الجدول، مثل {{ grandTotal }}.

المصدر وJSON النموذجي

اختر مصفوفة بيانات الجدول في «المصدر» وعدّل JSON النموذجي. يجب أن يطابق حقل العمود خاصية كائنات المصفوفة. لعرض quantity من items مثلًا، اضبط حقل العمود على quantity. عالج أي تحذير JSON غير صالح قبل المتابعة.

مظهر الجدول الافتراضي

القياسات هي القيم الافتراضية للمنتج: ترويسة 40px وصف 40px ومسافة داخلية للخلية 10px وحد 1px. يمكن للقالب تجاوز كل منها.

عنصر جدول من البداية إلى النهاية

يرتبط الجدول بمصفوفة في بياناتك ويرسم صفًا لكل عنصر. العنصر أدناه هو المرفق بقالب الفاتورة، ويمد الاستدعاء أسفله الجدول نفسه بثلاثة صفوف.

{
  "id": "invoice-items",
  "type": "table",
  "placementMode": "flow",
  "binding": "lineItems",
  "layout": { "x": 0, "y": 330, "width": 100, "widthUnit": "percent", "height": 220 },
  "style": {
    "tableHeaderHeight": 36,
    "tableRowHeight": 34,
    "tableRepeatHeader": true,
    "tablePreventRowSplit": true
  },
  "columns": [
    { "key": "name", "label": "الوصف", "valueTemplate": "{{ name }}",
      "align": "left", "widthPercent": 46 },
    { "key": "quantity", "label": "الكمية", "valueTemplate": "{{ quantity }}",
      "align": "right", "widthPercent": 14 },
    { "key": "unitPrice", "label": "سعر الوحدة", "valueTemplate": "{{ unitPrice }}",
      "align": "right", "widthPercent": 20,
      "format": { "kind": "currency", "currency": "USD", "decimals": 2 } },
    { "key": "total", "label": "المبلغ", "valueTemplate": "{{ total }}",
      "align": "right", "widthPercent": 20,
      "format": { "kind": "currency", "currency": "USD", "decimals": 2 } }
  ]
}

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "ar",
        "data": {
          "document": { "title": "ملخص الفاتورة" },
          "referenceNo": "DOC-2026-0042",
          "issueDate": "2026-09-06",
          "currency": "USD",
          "customer": "Northwind Trading Ltd.",
          "lineItems": [
            { "name": "تشخيص العطل", "quantity": 2, "unitPrice": 850.00 },
            { "name": "وحدة اتصال", "quantity": 1, "unitPrice": 2850.00 },
            { "name": "معايرة في الموقع", "quantity": 1, "unitPrice": 850.00 }
          ]
        }
      }'

تحدد binding المصفوفة في بياناتك، وتحدد key الحقل داخل كل عنصر، وتحدد valueTemplate ما يُطبع. تكرر tableRepeatHeader الترويسة في كل صفحة، وتمنع tablePreventRowSplit انقسام الصف عند فاصل الصفحة.

تطبيق الجداول الطويلة واختبارها

افحص ترتيب الأعمدة والحقول الفارغة والملخصات في المعاينة، ثم طبّق التغييرات على الجدول. اختبر بعدها صفر صفوف وصفًا واحدًا وصفوفًا كثيرة في معاينة المستند. يؤثر النص الطويل وارتفاع الترويسة والصف في تقسيم الصفحات؛ فلا تعتمد على نموذج قصير فقط.

عناصر dataset

يعرض عنصر dataset المجموعة المرتبط بها كجدول ويستنتج أعمدته من البيانات دون أن تصرّح بها. استخدمه عندما تحدد الحمولة بنية المجموعة بدلًا من القالب.

عناوين الأعمدة هي أسماء الحقول. لا يحمل عنصر dataset تسميات خاصة به؛ استخدم عنصر جدول إذا أردت تسمية الأعمدة بنفسك.

الأخطاء الشائعة

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