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

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

مقدمة

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

يدعم Aspose.Cells هذا السيناريو بطريقتين متكاملتين:

• النهج 1 — وضع صورة عائمة فوق خلية. أضف Picture إلى ورقة العمل، وعيّن خاصية Placement الخاصة بها إلى MoveAndSize، واضبط خلايا التثبيت الخاصة بها (UpperLeftRow، UpperLeftColumn، LowerRightRow، LowerRightColumn) بحيث تغطي الصورة خلية واحدة بالضبط.
• النهج 2 — تضمين صورة مباشرة في خلية. قم بتعيين بايتات الصورة إلى خاصية EmbeddedImage الخاصة بالخلية. تُعدَّل الصورة تلقائيًا لتناسب مساحة عرض الخلية وتنتقل معها.

يتناول باقي هذه المقالة كلا النهجين، ويشرح واجهات برمجة التطبيقات ذات الصلة، ويوضح كيفية استخدامها في التعليمات البرمجية.

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

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

لجعل الصورة العائمة تغطي خلية واحدة بالضبط، تحتاج إلى:

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

تثبيت الصورة في خلية واحدة

يتم تعريف تثبيت الصورة من خلال أربع خصائص فهرسة تبدأ من الصفر:

• picture.setUpperLeftRow(int) — فهرس الصف للحافة العلوية للصورة.
• picture.setUpperLeftColumn(int) — فهرس العمود للحافة اليسرى للصورة.
• picture.setLowerRightRow(int) — فهرس الصف للحافة السفلية للصورة. لجعل الحافة السفلية للصورة تقع في أسفل الصف r، عيّن هذه القيمة إلى r + 1.
• picture.setLowerRightColumn(int) — فهرس العمود للحافة اليمنى للصورة. لجعل الحافة اليمنى للصورة تقع على يمين العمود c، عيّن هذه القيمة إلى c + 1.

على سبيل المثال، لملاءمة الصورة بدقة في الخلية C6 (فهرس الصف 5، فهرس العمود 2)، عيّن UpperLeftRow = 5، وUpperLeftColumn = 2، وLowerRightRow = 6، وLowerRightColumn = 3.

تبدأ فهارس الصفوف والأعمدة في Aspose.Cells من الصفر. الخلية C6 لها فهرس صف 5 وفهرس عمود 2. تُعد أخطاء الإزاحة بمقدار واحد في مرساة الزاوية السفلية اليمنى المصدر الأكثر شيوعًا لظهور الصور وكأنها تتداخل إلى خلية مجاورة.

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

Picture.Placement هو تعداد من نوع PlacementType يتحكم في كيفية تصرف الصورة عندما يغير المستخدم حجم الصف أو العمود الموجود تحتها. القيمة الموصى بها لصورة خلية واحدة هي PlacementType.MoveAndSize، والتي تتسبب في تحرك الصورة وتغيير حجمها معًا مع خليتها الأساسية، مع الحفاظ على الملاءمة الدقيقة.

إرشادات خطوة بخطوة

1. أنشئ Workbook جديدًا (أو افتح ملفًا موجودًا).
2. الوصول إلى Worksheet المستهدفة من workbook.getWorksheets().get(0).
3. افتح ملف الصورة من القرص في InputStream (على سبيل المثال، باستخدام FileInputStream) بحيث يتم إغلاق التدفق بشكل صحيح.
4. استدعِ worksheet.getPictures().add(5, 2, stream) لإضافة صورة مثبتة في الخلية C6. احصل على مرجع Picture المُعاد.
5. عيّن إحداثيات التثبيت الأربعة بحيث تغطي الصورة الخلية C6 فقط: UpperLeftRow = 5، وUpperLeftColumn = 2، وLowerRightRow = 6، وLowerRightColumn = 3.
6. عيّن picture.setPlacement(PlacementType.MOVE_AND_SIZE) للحفاظ على محاذاة الصورة مع C6 عند تغيير حجم العمود أو الصف.
7. اختياريًا، أضف نصًا نموذجيًا إلى الخلايا المحيطة لإثبات أن الخلية C6 فقط هي التي تحتوي على الصورة.
8. احفظ المصنف على القرص كملف .xlsx.

توضح التعليمات البرمجية التالية النهج الكامل.

var workbook = new AsposeCells.Workbook();
var worksheet = workbook.getWorksheets().get(0);

var picIndex = worksheet.getPictures().add(5, 2, "logo.png");
var picture = worksheet.getPictures().get(picIndex);
picture.setUpperLeftRow(5);
picture.setUpperLeftColumn(2);
picture.setLowerRightRow(6);
picture.setLowerRightColumn(3);
picture.setPlacement(AsposeCells.PlacementType.MoveAndSize);

workbook.save("output.xlsx", AsposeCells.SaveFormat.Xlsx);

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

يعرض Aspose.Cells أيضًا آلية أبسط للصور المرتبطة بالخلايا: خاصية Cell.EmbeddedImage. يؤدي تعيين بايتات الصورة لهذه الخاصية إلى إرفاق الصورة بالخلية نفسها، كما لو كانت محتوى مضمّنًا.

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

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

هذا يجعل Cell.EmbeddedImage الخيار الأكثر إيجازًا عندما يكون هدفك ببساطة “صورة تعيش داخل هذه الخلية”.

إرشادات خطوة بخطوة

1. أنشئ Workbook جديدًا (أو افتح ملفًا موجودًا).
2. الوصول إلى Worksheet المستهدفة من workbook.getWorksheets().get(0).
3. اقرأ ملف الصورة من القرص في مصفوفة بايتات (على سبيل المثال، باستخدام Files.readAllBytes من java.nio.file.Files).
4. احصل على مرجع للخلية المستهدفة — إما من خلال worksheet.getCells().get("C6") أو worksheet.getCells().get(5, 2).
5. عيّن مصفوفة البايتات إلى خاصية EmbeddedImage الخاصة بالخلية عبر cell.setEmbeddedImage(bytes).
6. اختياريًا، اضبط ارتفاع الصف وعرض العمود للصف والعمود المستهدفين لمنح الصورة المضمنة مظهرًا أكثر بروزًا.
7. احفظ المصنف على القرص كملف .xlsx.

توضح التعليمات البرمجية التالية النهج الكامل.

var workbook = new AsposeCells.Workbook();
var worksheet = workbook.getWorksheets().get(0);

// الحصول على الخلية المستهدفة C6
var cell = worksheet.getCells().get("C6");

// قراءة ملف الصورة إلى مصفوفة بايتات
var imageData = fs.readFileSync("logo.png");

// تضمين الصورة مباشرة في الخلية
cell.setEmbeddedImage(imageData);

// اختيارياً ضبط ارتفاع الصف وعرض العمود لجعل الصورة المضمنة أكثر وضوحاً
worksheet.getCells().setColumnWidth(2, 30);   // العمود C (الفهرس 2)
worksheet.getCells().setRowHeight(5, 100);     // الصف 6 (الفهرس 5)

// حفظ المصنف الناتج كملف ‎.xlsx
workbook.save("output.xlsx", AsposeCells.SaveFormat.Xlsx);

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

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

• استخدم صورة عائمة (النهج 1) عندما:

  • تحتاج إلى تحكم أدق في الموضع أو الطبقات أو المحاذاة مع كائنات الرسم الأخرى.
  • تريد أن تتصرف الصورة كشكل يمكن تحديده أو إعادة ترتيبه أو تجميعه مع أشكال أخرى.
  • تتطلب توافقًا قديمًا مع التعليمات البرمجية التي تعمل بالفعل مع PictureCollection.
  • تحتاج إلى حساب إحداثيات التثبيت ديناميكيًا بناءً على تخطيط ورقة العمل.

• استخدم صورة مضمنة (النهج 2) عندما:

  • تريد أبسط إدراج ممكن لصورة في خلية.
  • يجب أن تنتقل الصورة مع الخلية مثل أي محتوى خلية آخر.
  • لا تحتاج إلى معالجة الصورة كشكل.

يمكن أن يتعايش النهجان في نفس المصنف. يمكنك وضع صور عائمة فوق مجموعة من الخلايا وتضمين الصور مباشرة في خلايا أخرى، حيث تستخدم الآليتان طبقات تخزين مختلفة في الملف.