دليل Apache POI الكامل لجافا: أمثلة عملية

1. ما هو Apache POI ولماذا تحتاجه؟

Apache POI (Poor Obfuscation Implementation) هي مكتبة قوية مفتوحة المصدر بلغة جافا، مصممة لإنشاء وقراءة وتعديل ملفات Microsoft Office (Excel, Word, PowerPoint, Outlook). تتيح للمطورين التحكم في المستندات برمجياً دون الحاجة إلى تثبيت حزمة Microsoft Office نفسها. توفر المكتبة واجهتين برمجيتين رئيسيتين: HSSF (Horrible Spreadsheet Format) للتعامل مع الملفات بصيغة .xls (Excel 97-2003) و XSSF (XML Spreadsheet Format) للتعامل مع الصيغة الحديثة .xlsx (Excel 2007+). بالنسبة لملفات Word، تُستخدم مكونات مشابهة: HWPF (لـ .doc) و XWPF (لـ .docx).

لماذا تحتاجها؟ في التطوير الحديث، كثيراً ما تظهر الحاجة لأتمتة العمل مع المستندات المكتبية: إنشاء التقارير، استيراد البيانات من الجداول، إعداد نماذج العقود، أو تكوين ملخصات تحليلية معقدة. Apache POI يحل هذه المشاكل، مانحاً مطوري جافا تحكماً كاملاً في بنية المستند: من تنسيق الخلايا وإنشاء الرسوم البيانية في Excel، إلى التعامل مع الجداول والصور والأنماط في Word.

المكتبة مدعومة بنشاط من مجتمع Apache Software Foundation، ولها توثيق شامل، وتُستخدم في مشاريع مؤسسية كبيرة. وهي متوافقة مع جافا 8 والإصدارات الأحدث، مما يجعلها أداة متعددة الاستخدامات لمعظم تطبيقات جافا الحديثة، بما في ذلك خدمات الويب والتطبيقات المكتبية وأنظمة معالجة البيانات.

2. التثبيت

يتم توزيع Apache POI عبر Maven Central Repository. لإضافته إلى مشروعك، يجب إضافة التبعيات إلى ملف pom.xml (لـ Maven) أو build.gradle (لـ Gradle).

Maven

<!-- التبعية الأساسية للعمل مع Excel (.xls و .xlsx) -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.3.0</version>
</dependency>

<!-- للعمل مع مستندات Word (.doc و .docx) -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-scratchpad</artifactId>
    <version>5.3.0</version>
</dependency>

Gradle

implementation 'org.apache.poi:poi-ooxml:5.3.0'
implementation 'org.apache.poi:poi-scratchpad:5.3.0'

ملاحظة مهمة: الإصدار 5.3.0 هو الأحدث وقت كتابة هذا المقال. يُنصح بالتحقق من أحدث إصدار على Maven Repository. لاحظ أيضاً أن poi-ooxml يتضمن بالفعل poi (الوحدة الأساسية) و poi-ooxml-lite (للعمل مع صيغ OOXML).

3. البداية السريعة: مثال عملي بسيط

لننشئ ملف Excel بسيطاً يحتوي على صف واحد من البيانات ونحفظه على القرص.

import org.apache.poi.ss.usermodel.*;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;

import java.io.FileOutputStream;
import java.io.IOException;

public class QuickStart {
    public static void main(String[] args) {
        // إنشاء مصنف جديد (Workbook) لصيغة .xlsx
        try (Workbook workbook = new XSSFWorkbook()) {
            // إنشاء ورقة عمل باسم "بيانات"
            Sheet sheet = workbook.createSheet("بيانات");

            // إنشاء صف (المؤشر 0 هو الصف الأول)
            Row row = sheet.createRow(0);

            // إنشاء خلية في العمود A (المؤشر 0)
            Cell cell = row.createCell(0);
            cell.setCellValue("مرحباً، Apache POI!");

            // إنشاء خلية في العمود B (المؤشر 1) بقيمة رقمية
            Cell cell2 = row.createCell(1);