كاميرا Excel في Aspose.Cells for Python عبر .NET

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

ما هي كاميرا Excel؟

كاميرا Excel هي في الأساس كائن صورة مثبّت عند صف وعمود محددين في طبقة الرسم الخاصة بورقة العمل. وعلى عكس الصورة العادية المُدرجة، ترتبط الكاميرا بنطاق مصدر من خلال صيغة بنمط A1 مثل "A1:F10". كلما تغيرت أي خلية داخل هذا النطاق، تتحدث صورة الكاميرا تلقائيًا لتعكس المحتوى الجديد. تحافظ الكاميرا على التنسيق الكامل لمنطقة المصدر، بما في ذلك الحدود وألوان الخلفية والخطوط وتنسيقات الأرقام، لذلك يظهر كل ما هو مرئي داخل الخلايا أيضًا في صورة الكاميرا. وهذا يجعل الكاميرا مفيدةً خصوصًا لوحات المعلومات والملخصات والأشرطة الجانبية وتخطيطات التقارير حيث تريد معاينة مرئية لمنطقة بعيدة دون التمرير أو تكرار البيانات. ثمة ملاحظتان مهمتان، وهما أنه يجب استدعاء update_selected_value() قبل حفظ المصنف، وأنه يجب تصدير الملف إلى HTML أو PDF لأن هذين التنسيقين يعتمدان على بيانات الصورة المضمّنة بدلاً من إعادة الحساب الحي.

الطريقة 1 — إضافة صورة كاميرا ديناميكية

تعد الكاميرا الديناميكية النهج الأكثر شيوعًا والأقرب إلى أداة الكاميرا المضمّنة في Excel. تعمل عن طريق إضافة صورة لا تحتوي على محتوى أولي، ثم تعيين خاصية formula للإشارة إلى نطاق المصدر. بعد تعيين الصيغة، يؤدي استدعاء update_selected_value() إلى تحديث بيانات الصورة المضمّنة بحيث تظل متزامنة مع الخلايا التي تعكسها. لا يتم تنفيذ الكاميرا من خلال فئة مخصصة، بل تُنشأ بالكامل باستخدام نوع Picture القياسي. تتمثل واجهات API الأساسية في:

  • PictureCollection.add(int upperLeftRow, int upperLeftColumn, Stream stream) — تضيف صورة مثبتة عند الصف والعمود المحددين. يؤدي تمرير None إلى معلمة stream إلى إنشاء صورة فارغة تعمل كعنصر نائب للكاميرا الديناميكية. تعيد الطريقة فهرس الصورة الجديدة.
  • worksheet.pictures[index] — يوفر الوصول من خلال الفهرس لاسترداد Picture محددة من المجموعة.
  • picture.formula — خاصية نصية (get/set) تحتوي على مرجع بنمط A1 إلى نطاق المصدر الذي تعكسه الكاميرا، مثل "A1:F10".
  • picture.update_selected_value() — طريقة بلا قيمة إرجاع تُحدّث بيانات الصورة المضمّنة من الخلايا المشار إليها بواسطة formula.

ينشئ الرمز التالي مصنفًا، ويضيف صورة فارغة مثبتة عند الصف 10 والعمود 6، ويربطها بنطاق المصدر A1:F10 من خلال الخاصية formula، ويحدث بيانات الصورة المضمّنة، ثم يحفظ المصنف.

from aspose.cells import Workbook, SaveFormat
workbook = Workbook()
worksheet = workbook.worksheets[0]
worksheet.name = "CameraDemo"
# الكاميرا الديناميكية: أضف صورة فارغة، اربطها عبر الصيغة بـ A1:F10، ثم حدّثها
pictures = worksheet.pictures
index = pictures.add(10, 6, None)
pictures[index].formula = "A1:F10"
pictures[index].update_selected_value()
workbook.save("output_dynamic.xlsx", SaveFormat.XLSX)

الطريقة 2 — إضافة صورة كاميرا ثابتة

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

  • Cells.create_range(string address) — تنشئ كائن Range من عنوان بنمط A1 مثل "A1:F10".
  • Range.to_image(ImageOrPrintOptions options) — تحوّل النطاق إلى وحدات بايت للصورة. يؤدي تمرير None إلى استخدام خيارات العرض الافتراضية، وتوجد حمولات زائدة لتوفير تحكم أدق في الناتج.
  • BytesIO(byte[] buffer) — يُغلِّف وحدات بايت الصورة المعروضة في BytesIO يمكن تمريره إلى PictureCollection.add.
  • PictureCollection.add(int upperLeftRow, int upperLeftColumn, Stream stream) — تضيف الصورة مثبتة عند الصف والعمود المحددين، مع تمرير BytesIO الناتج عن العرض هذه المرة. ينشئ الرمز التالي مصنفًا، وينشئ Range للنطاق A1:F10، ويحوّله إلى وحدات بايت للصورة من خلال Range.to_image(null)، ويلف وحدات البايت في BytesIO، ويضيف الصورة مثبتة عند الصف 10 والعمود 6، ثم يحفظ المصنف.
from io import BytesIO
from aspose.cells import Workbook, SaveFormat
workbook = Workbook()
worksheet = workbook.worksheets[0]
worksheet.name = "CameraDemo"
# الكاميرا الثابتة: بناء النطاق، التحويل إلى بايتات، التغليف في BytesIO، الإضافة كصورة
range_ = worksheet.cells.create_range("A1:F10")
pictures = worksheet.pictures
pictures.add(10, 6, BytesIO(range_.to_image(None)))
workbook.save("output_static.xlsx", SaveFormat.XLSX)

الاختيار بين الكاميرا الديناميكية والثابتة

  • الكاميرا الديناميكية: تُحدَّث عند كل عملية إعادة حساب، وتدعم تصدير HTML وPDF بعد استدعاء update_selected_value()، وتحافظ على سلوك الرابط الحي طوال عمر الملف.
  • الكاميرا الثابتة: هي صورة مُرسومة مرة واحدة لا تتحدّث أبدًا، وتكون مفيدة عندما تريد لقطة مرئية ثابتة مضمّنة في وقت البناء بدلاً من نسخة حية تعكس البيانات. يدعم Aspose.Cells كلًا من الكاميرا الديناميكية المتجددة تلقائيًا والمبنية على picture.formula مع update_selected_value()، والكاميرا الثابتة أحادية الالتقاط والمبنية على Range.to_image مع BytesIO. اختر النهج الديناميكي عندما يحتاج ناتجك إلى البقاء متزامنًا مع خلايا المصدر، واختر النهج الثابت عندما تحتاج فقط إلى لقطة مرئية ثابتة في وقت البناء.
إدارة مربع النص إضافة رموز إلى ورقة العمل