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

المقدمة

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

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

  • الأسلوب 1 — وضع صورة عائمة فوق خلية. أضف Picture إلى ورقة العمل، وعيّن placement الخاص بها إلى MOVE_AND_SIZE، واضبط خلايا الإرساء الخاصة بها (upper_left_row, upper_left_column, lower_right_row, lower_right_column) بحيث تغطي الصورة خلية واحدة بالضبط.
  • الأسلوب 2 — تضمين صورة مباشرة في خلية. عيّن وحدات بايت الصورة إلى خاصية embedded_image الخاصة بالخلية. تتمدد الصورة تلقائيًا لتلائم مساحة عرض الخلية وتنتقل معها.

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

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

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

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

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

ربط الصورة بخلية واحدة

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

  • Picture.upper_left_row — فهرس صف الحافة العلوية للصورة.
  • Picture.upper_left_column — فهرس عمود الحافة اليسرى للصورة.
  • Picture.lower_right_row — فهرس صف الحافة السفلية للصورة. لجعل الحافة السفلية للصورة تجلس في أسفل الصف r، عيّن هذا إلى r + 1.
  • Picture.lower_right_column — فهرس عمود الحافة اليمنى للصورة. لجعل الحافة اليمنى للصورة تجلس في يمين العمود c، عيّن هذا إلى c + 1.

على سبيل المثال، لضبط الصورة تمامًا داخل الخلية C6 (فهرس الصف 5، فهرس العمود 2)، عيّن upper_left_row = 5، وupper_left_column = 2، وlower_right_row = 6، وlower_right_column = 3.

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

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

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

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

يوضح الكود التالي الأسلوب الكامل.

import aspose.cells as ac

workbook = ac.Workbook()
worksheet = workbook.worksheets[0]

with open("logo.png", "rb") as fs:
    pic_index = worksheet.pictures.add(5, 2, fs)
    picture = worksheet.pictures[pic_index]
    picture.upper_left_row = 5
    picture.upper_left_column = 2
    picture.lower_right_row = 6
    picture.lower_right_column = 3
    picture.placement = ac.PlacementType.MOVE_AND_SIZE

workbook.save("output.xlsx", ac.SaveFormat.XLSX)

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

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

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

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

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

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

  1. أنشئ Workbook جديدًا (أو افتح واحدًا موجودًا).
  2. يمكنك الوصول إلى Worksheet المستهدف من workbook.worksheets[0].
  3. اقرأ ملف الصورة من القرص إلى كائن bytes (على سبيل المثال، بفتح الملف في الوضع الثنائي واستدعاء .read()).
  4. احصل على مرجع للخلية المستهدفة — إما من خلال worksheet.cells["C6"] أو worksheet.cells[5, 2].
  5. عيّن كائن البايتات إلى خاصية embedded_image الخاصة بالخلية.
  6. اختياريًا، اضبط ارتفاع الصف وعرض العمود للصف والعمود المستهدفين لإعطاء الصورة المضمنة مظهرًا أكثر وضوحًا.
  7. احفظ المصنف على القرص كملف .xlsx.

يوضح الكود التالي الأسلوب الكامل.

import aspose.cells as ac

workbook = ac.Workbook()
worksheet = workbook.worksheets[0]

# الحصول على الخلية المستهدفة C6
cell = worksheet.cells["C6"]

# قراءة ملف الصورة في مصفوفة بايتات
with open("logo.png", "rb") as f:
    imageData = f.read()

# تضمين الصورة مباشرة في الخلية
cell.embedded_image = imageData

# اختيارياً ضبط ارتفاع الصف وعرض العمود لتكون الصورة المضمنة أكثر وضوحاً
worksheet.cells.set_column_width(2, 30)   # العمود C (الفهرس 2)
worksheet.cells.set_row_height(5, 100)     # الصف 6 (الفهرس 5)

# حفظ المصنف الناتج كملف .xlsx
workbook.save("output.xlsx", ac.SaveFormat.XLSX)

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

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

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

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

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

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

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

تحميل صورة ويب من عنوان URL إلى ورقة عمل إكسل إدراج صورة بناءً على مرجع الخلية