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

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

المقدمة

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

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

• الطريقة 1 — وضع صورة عائمة فوق خلية. أضف Picture إلى ورقة العمل، واضبط setPlacement على MOVE_AND_SIZE، وعدّل خلايا الارتكاز الخاصة بها (setUpperLeftRow، setUpperLeftColumn، setLowerRightRow، setLowerRightColumn) بحيث تغطي الصورة خلية واحدة بالضبط.
• الطريقة 2 — تضمين صورة مباشرة في خلية. خصّص وحدات بايت الصورة لخاصية setEmbeddedImage الخاصة بالخلية. تتدرج الصورة تلقائيًا لتلائم مساحة عرض الخلية وتنتقل معها.

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

الطريقة 1: وضع صورة فوق خلية

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

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

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

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

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

• setUpperLeftRow — فهرس الصف للحافة العلوية للصورة.
• setUpperLeftColumn — فهرس العمود للحافة اليسرى للصورة.
• setLowerRightRow — فهرس الصف للحافة السفلية للصورة. لجعل الحافة السفلية للصورة في أسفل الصف r، اضبط هذا على r + 1.
• setLowerRightColumn — فهرس العمود للحافة اليمنى للصورة. لجعل الحافة اليمنى للصورة في يمين العمود c، اضبط هذا على c + 1.

على سبيل المثال، لضبط الصورة بدقة في الخلية C6 (فهرس الصف 5، فهرس العمود 2)، اضبط setUpperLeftRow(5)، وsetUpperLeftColumn(2)، وsetLowerRightRow(6)، وsetLowerRightColumn(3).

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

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

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

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

1. أنشئ Workbook جديدًا (أو افتح ملفًا موجودًا).
2. قم بالوصول إلى Worksheet المستهدف من workbook.getWorksheets().get(0).
3. افتح ملف الصورة من القرص في InputStream (عادةً FileInputStream) بحيث يتم إغلاق التدفق بشكل صحيح.
4. استدعِ worksheet.getPictures().add(5, 2, stream) لإضافة صورة مرتبطة بالخلية C6. احفظ مرجع Picture المُرجع.
5. اضبط إحداثيات الارتكاز الأربعة بحيث تغطي الصورة الخلية C6 فقط: setUpperLeftRow(5)، وsetUpperLeftColumn(2)، وsetLowerRightRow(6)، وsetLowerRightColumn(3).
6. اضبط picture.setPlacement(PlacementType.MOVE_AND_SIZE) للحفاظ على محاذاة الصورة مع C6 عند تغيير حجم العمود أو الصف.
7. اختياريًا، أضف نصًا نموذجيًا إلى الخلايا المحيطة لإثبات أن الخلية C6 فقط تحتوي على الصورة.
8. احفظ المصنف على القرص كملف .xlsx.

توضح التعليمات البرمجية التالية الطريقة الكاملة.

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, SaveFormat, PlacementType

workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)

FileInputStream = jpype.JClass("java.io.FileInputStream")
fs = FileInputStream("logo.png")
try:
    picIndex = worksheet.getPictures().add(5, 2, fs)
    picture = worksheet.getPictures().get(picIndex)
    picture.setUpperLeftRow(5)
    picture.setUpperLeftColumn(2)
    picture.setLowerRightRow(6)
    picture.setLowerRightColumn(3)
    picture.setPlacement(PlacementType.MoveAndSize)
finally:
    fs.close()

workbook.save("output.xlsx", SaveFormat.Xlsx)

jpype.shutdownJVM()

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

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

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

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

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

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

1. أنشئ Workbook جديدًا (أو افتح ملفًا موجودًا).
2. قم بالوصول إلى Worksheet المستهدف من workbook.getWorksheets().get(0).
3. اقرأ ملف الصورة من القرص في مصفوفة byte[] (على سبيل المثال، باستخدام استدعاء Files.readallbytes من java.nio.file.Files).
4. احصل على مرجع للخلية المستهدفة — إما من خلال worksheet.getCells().get("C6") أو worksheet.getCells().get(5, 2).
5. خصّص مصفوفة البايت لخاصية setEmbeddedImage الخاصة بالخلية.
6. اختياريًا، اضبط ارتفاع الصف وعرض العمود للصف والعمود المستهدفين لإعطاء الصورة المضمنة مظهرًا أكثر بروزًا.
7. احفظ المصنف على القرص كملف .xlsx.

توضح التعليمات البرمجية التالية الطريقة الكاملة.

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, Worksheet, Cells, Range, SaveFormat

# الكود المحمّل هنا
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)

# الحصول على الخلية المستهدفة C6
cell = worksheet.getCells().get("C6")

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

# تضمين الصورة مباشرة في الخلية
cell.setEmbeddedImage(imageData)

# اختياريًا، ضبط ارتفاع الصف وعرض العمود لتكون الصورة المضمنة أكثر وضوحًا
worksheet.getCells().setColumnWidth(2, 30)   # العمود C (المؤشر 2)
worksheet.getCells().setRowHeight(5, 100)    # الصف 6 (المؤشر 5)

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

jpype.shutdownJVM()

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

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

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

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

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

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

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