إدراج صورة في خلية

مقدمة

يُعدّ جعل الصورة ملائمة لخلية واحدة تمامًا متطلبًا شائعًا عند تصميم جداول بيانات تُستخدم كتقارير مرئية أو فهارس منتجات أو أدلة لموظفين أو لوحات معلومات أو قوائم جرد. بدلاً من تمديد صورة عبر خلايا كثيرة أو وضعها بصورة غير مرتبطة على ورقة عمل، قد ترغب في صورة مرتبطة بإحكام بالخلية تبقى محاذاة لها. يدعم Aspose.Cells هذا السيناريو بطريقتين متكاملتين:

  • النهج 1 — وضع صورة عائمة فوق خلية. أضف Picture إلى ورقة العمل، واضبط Placement على MOVE_AND_SIZE، ثم اضبط خلايا الارتكاز (getUpperLeftRow, getUpperLeftColumn, getLowerRightRow, getLowerRightColumn) بحيث تغطي الصورة خلية واحدة بالضبط.
  • النهج 2 — تضمين صورة مباشرة داخل خلية. عيّن بايتات الصورة على المُعيّن getEmbeddedImage() الخاص بالخلية. تتكيف الصورة تلقائيًا مع منطقة عرض الخلية وتنتقل معها. يتناول بقية هذا المقال كلا النهجين، ويشرح واجهات API ذات الصلة، ويوضح كيفية استخدامها في التعليمات البرمجية.

النهج 1: وضع صورة فوق خلية

الصورة العائمة هي كائن Picture موجود في طبقة الرسم الخاصة بورقة العمل. وعلى الرغم من أنه ليس جزءًا من أي خلية بعينها، فإنImage مرتبط بنطاق من الخلايا. تحدد خلايا ارتكاز الصورة — أي زاويتها العلوية اليسرى والسفلية اليمنى — امتدادها المرئي على ورقة العمل. افتراضيًا، تمتد الصورة المضافة حديثًا عبر عدة خلايا. لجعل الصورة العائمة تغطي خلية واحدة بالضبط، عليك تنفيذ ما يلي:

  1. أضف الصورة باستخدام Worksheet.getPictures().add(int row, int column, InputStream stream)، وهو أسلوب يربط الصورة الجديدة بالخلية المحددة.
  2. اضبط خصائص الارتكاز الأربع بحيث يتطابق مستطيل حدود الصورة مع الخلية الهدف.
  3. اضبط Picture.setPlacement() على PlacementType.MOVE_AND_SIZE حتى تتحرك الصورة ويُغيَّر حجمها مع الخلية التي تنتمي إليها عندما يغيّر المستخدم عرض العمود أو ارتفاع الصف.

ربط الصورة بخلية واحدة

يحدد ارتباط الصورة أربع خصائص ذات فهارس مستندة إلى الصفر:

  • Picture.getUpperLeftRow() — فهرس الصف للحافة العليا للصورة.
  • Picture.getUpperLeftColumn() — فهرس العمود للحافة اليسرى للصورة.
  • Picture.getLowerRightRow() — فهرس الصف للحافة السفلية للصورة. لجعل الحافة السفلية للصورة عند الحد السفلي للصف r، اضبط هذا على r + 1.
  • Picture.getLowerRightColumn() — فهرس العمود للحافة اليمنى للصورة. لجعل الحافة اليمنى للصورة عند الحد الأيمن للعمود c، اضبط هذا على c + 1.

التحكم في سلوك الموضع

تتحكم القيمة التي يُرجعها Picture.getPlacement()، وهي تعداد من النوع PlacementType، في سلوك الصورة عندما يغيّر المستخدم حجم الصف أو العمود الواقع أسفلها. القيمة الموصى بها لصورة الخلية الواحدة هي PlacementType.MOVE_AND_SIZE، وهي تؤدي إلى تحريك الصورة وتغيير حجمها مع الخلية التي تنتمي إليها، مع الحفاظ على الملاءمة التامة.

تعليمات خطوة بخطوة

  1. أنشئ Workbook جديدًا أو افتح مصنفًا موجودًا.
  2. احصل على Worksheet الهدف من workbook.getWorksheets().get(0).
  3. افتح ملف الصورة الموجود على القرص في InputStream، مثل FileInputStream، باستخدام كتلة try-with-resources لضمان إغلاق التدفق بشكل صحيح.
  4. استدعِ worksheet.getPictures().add(5, 2, stream) لإضافة صورة مرتبطة بالخلية C6، واحتفظ بمرجع Picture الذي يُرجعه الأسلوب.
  5. اضبط إحداثيات الارتكاز الأربع بحيث تغطي الصورة الخلية C6 فقط: setUpperLeftRow(5)، وsetUpperLeftColumn(2)، وsetLowerRightRow(6)، وsetLowerRightColumn(3).
  6. اضبط picture.setPlacement(PlacementType.MOVE_AND_SIZE) للحفاظ على محاذاة الصورة مع C6 عند تغيير حجم العمود أو الصف.
  7. يمكنك اختياريًا إضافة نص تجريبي إلى الخلايا المجاورة لإظهار أن الخلية C6 فقط هي التي تحتوي على الصورة.
  8. احفظ المصنف على القرص في ملف .xlsx. يوضح التعليمة البرمجية التالية هذا النهج بالكامل.
import com.aspose.cells.*;
import java.io.FileInputStream;
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.getWorksheets().get(0);
try (FileInputStream fs = new FileInputStream("logo.png"))
{
    int picIndex = worksheet.getPictures().add(5, 2, fs);
    Picture picture = worksheet.getPictures().get(picIndex);
    picture.setUpperLeftRow(5);
    picture.setUpperLeftColumn(2);
    picture.setLowerRightRow(6);
    picture.setLowerRightColumn(3);
    picture.setPlacement(PlacementType.MOVE_AND_SIZE);
}
workbook.save("output.xlsx", SaveFormat.XLSX);

النهج 2: تضمين صورة مباشرة داخل خلية

يوفر Aspose.Cells أيضًا آلية أبسط للصور المرتبطة بالخلايا: طريقة Cell.setEmbeddedImage(byte[]). تؤدي عملية تعيين بايتات الصورة إلى هذه الخاصية إلى إرفاق الصورة بالخلية نفسها، كما لو كانت جزءًا من المحتوى المضمّن.

كيف تعمل الصور المضمَّنة

  • تُخزَّن الصورة كجزء من محتوى الخلية بدلاً من أن تكون شكلًا في طبقة الرسم.
  • تتكيف الصورة تلقائيًا لتلائم الحدود المعروضة للخلية. ولا يلزم أي إحداثيات ارتباط أو إعدادات موضع.
  • تظل الخلية خلية فعلية ذات عنوان فعلي، ويمكن الإشارة إليها في الصيغ أو فرزها ضمن صف أو استخدامها في عمليات أخرى على مستوى الخلية. يجعل هذا setEmbeddedImage() الخيار الأكثر إيجازًا عندما يكون هدفك ببساطة “صورة موجودة داخل هذه الخلية”.

تعليمات خطوة بخطوة

  1. أنشئ Workbook جديدًا أو افتح مصنفًا موجودًا.
  2. احصل على Worksheet الهدف من workbook.getWorksheets().get(0).
  3. اقرأ ملف الصورة من القرص إلى مصفوفة byte[]، على سبيل المثال، بقراءة الملف باستخدام Files.readAllBytes() من java.nio.file.
  4. احصل على مرجع إلى الخلية الهدف، إما عبر worksheet.getCells().get("C6") أو worksheet.getCells().get(5, 2).
  5. عيّن مصفوفة البايتات إلى الخلية باستخدام cell.setEmbeddedImage(bytes).
  6. يمكنك اختياريًا ضبط ارتفاع الصف وعرض العمود المستهدفَين لجعل الصورة المضمَّنة أكثر وضوحًا.
  7. احفظ المصنف على القرص في ملف .xlsx. يوضح التعليمة البرمجية التالية هذا النهج بالكامل.
import com.aspose.cells.*;
import java.nio.file.Files;
import java.nio.file.Paths;
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.getWorksheets().get(0);
// احصل على الخلية الهدف C6
Cell cell = worksheet.getCells().get("C6");
// اقرأ ملف الصورة إلى مصفوفة بايتات
byte[] imageData = Files.readAllBytes(Paths.get("logo.png"));
// ضمّن الصورة مباشرةً في الخلية
cell.setEmbeddedImage(imageData);
// اضبط ارتفاع الصف وعرض العمود اختياريًا حتى تكون الصورة المضمّنة أكثر وضوحًا
worksheet.getCells().setColumnWidth(2, 30);   // العمود C (الفهرس 2)
worksheet.getCells().setRowHeight(5, 100);     // الصف 6 (الفهرس 5)
// احفظ مصنف العمل الناتج كملف ‎.xlsx
workbook.save("output.xlsx", SaveFormat.XLSX);

اختيار النهج المناسب

ينتج كل من النهجين صورة تتلائم داخل خلية واحدة، لكنهما يختلفان في طريقة تخزين الصورة وسلوكها:

  • استخدم صورة عائمة (النهج 1) عندما:
    • تحتاج إلى تحكم أدق في الوضع أو الطبقات أو المحاذاة مع كائنات رسم أخرى.
    • تريد أن تتصرف الصورة كشكل يمكن تحديده أو إعادة ترتيبه أو تجميعه مع أشكال أخرى.
    • تحتاج إلى توافق مع الشفرة القديمة التي تتعامل بالفعل مع PictureCollection.
    • تحتاج إلى حساب إحداثيات الارتكاز ديناميكيًا بناءً على تخطيط ورقة العمل.
  • استخدم صورة مضمَّنة (النهج 2) عندما:
    • تريد أبسط طريقة ممكنة لإدراج صورة في خلية.
    • تريد أن تنتقل الصورة مع الخلية مثل أي محتوى آخر في الخلية.

مقالات ذات صلة