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

Introduction

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

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

Approach 1: Place a Picture Over a Cell

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

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

Anchoring the Picture to a Single Cell

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

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

Controlling Placement Behavior

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

Step-by-Step Instructions

  1. أنشئ Workbook جديدًا (أو افتح ملفًا موجودًا).
  2. الوصول إلى Worksheet المستهدف من workbook.worksheets[0].
  3. افتح ملف الصورة من القرص في دفق، مع التأكد من إغلاق الدفق بشكل صحيح بعد الاستخدام.
  4. استدعِ worksheet.pictures.add(5, 2, imageBytes) لإضافة صورة مُرتبطة بالخلية 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.node");
const fs = require("fs");
const workbook = new AsposeCells.Workbook();
const worksheet = workbook.getWorksheets().get(0);
const imageBytes = fs.readFileSync("logo.png");
const picIndex = worksheet.getPictures().add(5, 2, imageBytes);
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);

Approach 2: Embed an Image Directly in a Cell

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

How Embedded Images Work

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

Step-by-Step Instructions

  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. يوضح الكود التالي الأسلوب الكامل.
const AsposeCells = require("aspose.cells.node");
const fs = require("fs");
var workbook = new AsposeCells.Workbook();
var worksheet = workbook.getWorksheets().get(0);
// Get the target cell C6
var cell = worksheet.getCells().get("C6");
// Read the image file into a byte array
var imageData = fs.readFileSync("logo.png");
// Embed the image directly into the cell
cell.setEmbeddedImage(imageData);
// Optionally adjust row height and column width so the embedded image is more visible
worksheet.getCells().setColumnWidth(2, 30);   // Column C (index 2)
worksheet.getCells().setRowHeight(5, 100);     // Row 6 (index 5)
// Save the resulting workbook as an .xlsx file
workbook.save("output.xlsx", AsposeCells.SaveFormat.Xlsx);

Choosing the Right Approach

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

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