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

المقدمة

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

يدعم 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.

على سبيل المثال، لضبط الصورة بدقة في الخلية C6 (فهرس الصف 5، فهرس العمود 2)، عيّن upperLeftRow = 5، وupperLeftColumn = 2، وlowerRightRow = 6، وlowerRightColumn = 3.

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

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

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

  1. أنشئ Workbook جديدًا (أو افتح ملفًا موجودًا).
  2. الوصول إلى Worksheet المستهدفة من workbook.worksheets[0].
  3. افتح ملف الصورة من القرص في تدفق (stream)، مع التأكد من إغلاق التدفق بشكل صحيح بعد الاستخدام.
  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);

اختيار الطريقة المناسبة

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

  • استخدم صورة عائمة (الطريقة الأولى) عندما:

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

  • استخدم صورة مضمنة (الطريقة الثانية) عندما:

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

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

تحميل صورة ويب من عنوان URL إلى ورقة إكسل باستخدام Node.js عبر C++ إدراج صورة استنادًا إلى مرجع خلية باستخدام Node.js عبر C++