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

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

مقدمة

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

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

الأسلوب الأول: وضع صورة فوق خلية

الصورة العائمة هي كائن 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.

مؤشرات الصفوف والأعمدة في 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. يوضح الكود التالي الأسلوب الكامل.

const AsposeCells = require("aspose.cells-node");
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);

الأسلوب الثاني: تضمين صورة مباشرة في خلية

يعرض 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. يوضح الكود التالي الأسلوب الكامل.

const AsposeCells = require("aspose.cells-node");
const fs = require("fs");
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);

اختيار الأسلوب المناسب

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

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