إنشاء التقارير بـ JasperReports

JasperReports مكتبة Java لتصميم التقارير وإنشائها. يُكتب تخطيط التقرير في قالب `.jrxml`، وتُملأ البيانات من قاعدة بيانات أو من كائنات Java، ثم تُصدَّر النتيجة إلى PDF أو Excel أو HTML. تعرض هذه المقالة بنية القالب وكودًا ينشئ تقريرًا من قائمة صفوف.

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

ما الذي تحتاجه

• JDK 17 أو أحدث
• مكتبة JasperReports عبر Maven، مثلًا `net.sf.jasperreports:jasperreports`
• أداة تصميم مثل Jaspersoft Studio لتصميم القوالب بالسحب والإفلات

طريقة العمل

الخطوة 1: تصميم القالب

الملف `.jrxml` هو XML يحدد حقول البيانات والترويسة وصفوف التفاصيل والتذييل. أمثلة على الحقول:

<field name="name" class="java.lang.String"/>
<field name="score" class="java.lang.Integer"/>

في قسم `<detail>` أضف `textField` يشير إلى `$F{name}` و`$F{score}` لعرض قيم كل صف.

الخطوة 2: تجهيز البيانات وإنشاء التقرير

import net.sf.jasperreports.engine.*;
import net.sf.jasperreports.engine.data.JRBeanCollectionDataSource;
import java.util.List;
import java.util.Map;

public class ReportDemo {
    public static class Row {
        private final String name;
        private final int score;
        public Row(String name, int score) { this.name = name; this.score = score; }
        public String getName() { return name; }
        public int getScore() { return score; }
    }

    public static void main(String[] args) throws Exception {
        List<Row> rows = List.of(new Row("สมชาย", 85), new Row("สมหญิง", 72));
        JasperReport report = JasperCompileManager.compileReport("scores.jrxml");
        JasperPrint print = JasperFillManager.fillReport(report, Map.of(), new JRBeanCollectionDataSource(rows));
        JasperExportManager.exportReportToPdfFile(print, "scores.pdf");
    }
}

• تحوّل `compileReport` ملف `.jrxml` إلى صيغة قابلة للتشغيل.
• تدمج `fillReport` القالب مع البيانات.
• تكتب `exportReportToPdfFile` ملف PDF.

أخطاء شائعة

• **أسماء الحقول لا تطابق الدوال Getter:** يجب أن تتطابق الأسماء تمامًا.
• **خط اللغة التايلاندية لا يظهر:** حدد في القالب والنظام خطًا يدعم التايلاندية.
• **عدم ضبط الترميز:** تأكد من أن ملف `.jrxml` والنصوص في الكود بترميز UTF-8.

الخطوات التالية

أضف مجموعة إلى التقرير، مثل مجاميع لكل مادة، أو مرّر اسم المدرسة إلى التقرير كمعامل.

الخلاصة

يفصل JasperReports التخطيط عن البيانات. يحدد القالب الشكل، ويملأ الكود البيانات، ثم يُصدَّر التقرير بالصيغة المطلوبة. وهذا يسمح بتغيير تخطيط التقارير دون لمس الكود الأساسي.