مخطط JSON للقالب

بنية التعريف

تعريف القالب كائن واحد بجزأين: تحدد page الورقة، وتمثل elements القائمة المرتبة التي تُرسم عليها.

JSON

{
  "page": {
    "size": "A4",
    "orientation": "portrait",
    "margin": { "top": 48, "right": 48, "bottom": 48, "left": 48 }
  },
  "elements": [
    {
      "id": "invoice-title",
      "type": "heading",
      "placementMode": "flow",
      "content": { "text": "Invoice" },
      "layout": { "width": 100, "widthUnit": "percent", "height": 40 },
      "style": { "fontSize": 24, "textStyle": "bold" }
    }
  ]
}

أحجام الصفحات: A4 · A3 · Letter. يكون الاتجاه portrait أو landscape، والهوامش ببكسلات CSS بمعدل 96 بكسل لكل بوصة.

الحقول التي يقبلها كل عنصر

يتضمن كل عنصر id, type, placementMode. يعتمد الباقي على النوع، ويُنشأ الجدول أدناه من القواعد نفسها التي يستخدمها المدقق، فلا يمكن أن يتأخر عن المنتج.

type	الحقول المقبولة
`chart`	band · binding · chart · content · dataRules · layout · style
`container`	band · container · dataRules · layout
`dataset`	band · binding · dataRules · layout · style
`footer`	band · binding · content · dataRules · layout · style
`header`	band · binding · content · dataRules · layout · style
`heading`	band · binding · content · dataRules · layout · style
`image`	band · binding · content · dataRules · layout · style
`pagebreak`	band · dataRules
`pagenumber`	band · content · dataRules · layout · style
`table`	band · binding · columns · content · dataRules · layout · style · summaryRows
`text`	band · binding · content · dataRules · layout · style

يفشل التحقق من حقل غير موجود في صف نوعه بدلًا من تجاهله. فحذف الحقل بصمت أسوأ: يخرج المستند ناقصًا ويبدو الطلب ناجحًا.

placementMode

كيفية تحديد موضع العنصر على الورقة. يحدد الوضع أيضًا ما إذا كانت layout.x وlayout.y تُقرآن أصلًا.

flow — تُرتب تباعًا إلى أسفل الصفحة؛ تُتجاهل x وy ويتوسع العنصر مع محتواه
free — يوضع عند layout.x وlayout.y، تمامًا حيث حددته
band — يتكرر في كل صفحة ضمن النطاق الذي يسميه العنصر، مثل الترويسة أو التذييل

عنصر dataset

يطبع dataset مجموعة ليست جدولًا: قائمة زيارات أو صور أو توقيعات، تُرسم بالتخطيط الذي يمنحه القالب بدل الأعمدة.

JSON

{
  "id": "maintenance-visits",
  "type": "dataset",
  "placementMode": "flow",
  "binding": "visits",
  "layout": { "width": 100, "widthUnit": "percent", "height": 160 },
  "style": { "fontSize": 11 },
  "dataRules": { "required": true }
}

تحدد binding المصفوفة في بياناتك كما في الجدول تمامًا. يعتمد ما يُرسم لكل عنصر على التخطيط والنمط، لذا قد تكون المجموعة نفسها جدولًا في قالب وdataset في آخر.

ليس لـ dataset حقل content. تُغذيه binding فقط؛ فالنص الذي كان في content لم يصل إلى المخرجات قط، لذا أُزيل الحقل بدل تركه موضعًا للكتابة دون أثر.

فحص بياناتك قبل الإنشاء

يجيب طرف التحقق عن السؤال الذي يجيب عنه الإنشاء دون استهلاك الحصة: هل تلبي هذه البيانات متطلبات القالب؟

cURL

curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/validate-data \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "referenceNo": "DOC-2026-0042", "currency": "USD" } }'

تنسيقات البيانات →

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

يفشل التحقق من حقل لا ينتمي إلى نوع عنصره بدل تجاهله. هذا مقصود؛ فحذف حقل بصمت ينتج مستندًا ناقصًا ولا يبحث أحد عما لا يراه.
في موضع flow لا تُقرأ layout.x وlayout.y أصلًا. تعيينهما ثم التساؤل عن سبب عدم التحرك هو السؤال الأكثر شيوعًا عن المخطط.
ليس لـ dataset حقل content؛ تُغذيه binding فقط. النص الموضوع في content لا يصل إلى المخرجات.
الهوامش والأحجام ببكسلات CSS بمعدل 96 لكل بوصة، لا بالملليمترات. كتابة 20 على أساس الملليمترات تنتج حجمًا أصغر بنحو ثلاث مرات.
يكلف الإنشاء للتحقق من ملاءمة البيانات صفحة. يجيب طرف التحقق عن السؤال نفسه دون تكلفة.