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

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

مقدمة

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

• الأسلوب الأول — وضع صورة عائمة فوق خلية. أضف Picture إلى ورقة العمل، وعيّن خاصية placement إلى MoveAndSize، واضبط خلايا الإرساء (upperLeftRow، upperLeftColumn، lowerRightRow، lowerRightColumn) بحيث تغطي الصورة خلية واحدة بالضبط.
• الأسلوب الثاني — تضمين صورة مباشرة في خلية. عيّن بايتات الصورة إلى خاصية embeddedImage الخاصة بالخلية. تتدرج الصورة تلقائيًا لتلائم منطقة عرض الخلية وتنتقل معها. يتناول باقي هذه المقالة كلا الأسلوبين، ويوضح واجهات برمجة التطبيقات ذات الصلة، ويبيّن كيفية استخدامها في الكود.

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

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

1. إضافة الصورة باستخدام worksheet.pictures.add(row, column, stream)، والذي يربط الصورة الجديدة بالخلية المُحددة.
2. تعيين خصائص الإرساء الأربعة بحيث يتطابق المستطيل المحيط بالصورة مع الخلية المستهدفة.
3. تعيين picture.placement إلى PlacementType.MoveAndSize بحيث تتحرك الصورة ويتغيّر حجمها مع الخلية الأساسية عندما يقوم المستخدم بتغيير عرض العمود أو ارتفاع الصف.

إرساء الصورة في خلية واحدة

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

• picture.upperLeftRow — فهرس الصف للحافة العلوية للصورة.
• picture.upperLeftColumn — فهرس العمود للحافة اليسرى للصورة.
• picture.lowerRightRow — فهرس الصف للحافة السفلية للصورة. لجعل الحافة السفلية للصورة تقع في أسفل الصف r، عيّن هذا إلى r + 1.
• picture.lowerRightColumn — فهرس العمود للحافة اليمنى للصورة. لجعل الحافة اليمنى للصورة تقع في يمين العمود c، عيّن هذا إلى c + 1.

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

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

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

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

1. أنشئ Workbook جديدًا (أو افتح ملفًا موجودًا).
2. الوصول إلى Worksheet المستهدف من workbook.worksheets[0].
3. افتح ملف الصورة من القرص في دفق، مع التأكد من إغلاق الدفق بشكل صحيح بعد الاستخدام.
4. استدعِ worksheet.pictures.add(5, 2, stream) لإضافة صورة مُرتبطة بالخلية C6. احفظ مرجع Picture المُعاد.
5. عيّن إحداثيات الإرساء الأربعة بحيث تغطي الصورة الخلية C6 فقط: upperLeftRow = 5، upperLeftColumn = 2، lowerRightRow = 6، lowerRightColumn = 3.
6. عيّن picture.placement = PlacementType.MoveAndSize للحفاظ على محاذاة الصورة مع C6 عند تغيير حجم العمود أو الصف.
7. اختياريًا، أضف نصًا نموذجيًا إلى الخلايا المحاورة لإثبات أن الخلية C6 فقط تحتوي على الصورة.
8. احفظ المصنف على القرص كملف .xlsx. يوضح الكود التالي الأسلوب الكامل.

const AsposeCells = require("aspose.cells");
const fs = require("fs");
const workbook = new AsposeCells.Workbook();
const worksheet = workbook.getWorksheets().get(0);
const fs_stream = fs.createReadStream("logo.png");
const picIndex = worksheet.getPictures().add(5, 2, fs_stream);
const 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.worksheets[0].
3. اقرأ ملف الصورة من القرص في Buffer أو مصفوفة بايتات باستخدام واجهات برمجة نظام الملفات في Node.js (على سبيل المثال، fs.readFileSync).
4. احصل على مرجع للخلية المستهدفة — إما من خلال worksheet.cells["C6"] أو worksheet.cells[5, 2].
5. عيّن مصفوفة البايتات إلى خاصية embeddedImage الخاصة بالخلية.
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) عندما:
  • تحتاج إلى تحكم أدق في الموضع أو الطبقات أو المحاذاة مع كائنات الرسم الأخرى.
  • تريد أن تتصرف الصورة كشكل يمكن تحديده أو إعادة ترتيبه أو تجميعه مع أشكال أخرى.
  • تتطلب توافقًا قديمًا مع الكود الذي يعمل بالفعل مع مجموعة الصور.
  • تحتاج إلى حساب إحداثيات الإرساء ديناميكيًا بناءً على تخطيط ورقة العمل.
• استخدم صورة مُضمَّنة (الأسلوب 2) عندما:
  • تريد أبسط إدراج ممكن لصورة في خلية.
  • يجب أن تنتقل الصورة مع الخلية كما لو كانت أي محتوى آخر للخلية.

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

• كاميرا Excel في Aspose.Cells for Node.js via C++
• إضافة حقول التصفية إلى جدول محوري في Aspose.Cells for Node.js via C++
• تطبيق الأنماط على الجداول المحورية في Aspose.Cells for Node.js via C++
• تعديل تخطيط حقل الصفحة في الجدول المحوري
• تحويل Sparkline إلى صورة وHTML في Aspose.Cells for Node.js via C++