عرض مصفوفة الخلية الواحدة في SmartMarker | Aspose.Cells for Python via .NET

يدعم Aspose.Cells عرض بيانات المصفوفة في خلية واحدة عبر العلامات الذكية. من خلال استخدام سمة ArrayAsSingle مع سمة ExtraDelimiter، يمكن للمطورين التحكم في كيفية فصل عناصر المصفوفة داخل خلية واحدة، مما يوفر تنسيقًا مرنًا للتقارير والقوالب.

المقدمة

تعد العلامات الذكية في Aspose.Cells ميزة قوية قائمة على القوالب تتيح لك تعبئة بيانات جداول البيانات ديناميكيًا باستخدام تعبيرات العلامات مثل &=DataSource.Field. توضع العلامة في مصنف المصمم، وعندما يقوم WorkbookDesigner بمعالجة القالب، يتم استبدال العلامات بقيم من مصدر البيانات المقدم.

افتراضيًا، عندما تشير علامة ذكية إلى خاصية مصفوفة (على سبيل المثال، &=DataSource.Numbers)، يقوم المحرك بتوسيع المصفوفة ويضع كل عنصر في خلية منفصلة متجاورة — سواء أفقيًا عبر صف أو عموديًا لأسفل عمود. في حين أن هذا السلوك مناسب في العديد من السيناريوهات، إلا أن هناك مواقف قد تفضل فيها عرض المصفوفة بأكملها في خلية واحدة، مع دمج العناصر وفصلها بفاصل من اختيارك.

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

سبب الحاجة إلى هذه الميزة

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

عندما تشير علامة ذكية إلى خاصية مصفوفة، يقوم Aspose.Cells بتوسيع المصفوفة عبر خلايا متعددة افتراضيًا. على سبيل المثال، ستضع علامة مثل &=Product.Tags مقابل string[] يحتوي على أربع قيم كل قيمة في خليتها الخاصة، مما يدفع محتوى القالب الآخر إلى الخارج ويحتمل أن يكسر تخطيطات التقارير المصممة بعناية.

قيود حالات الاستخدام

هناك العديد من السيناريوهات العملية التي يكون فيها سلوك الانتشار الافتراضي غير مرغوب فيه:

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

الفجوة التي تسدها

بدون آلية مدمجة، سيُجبر المطورون على معالجة البيانات مسبقًا في Python — دمج المصفوفات في سلاسل نصية مفصولة قبل ربطها بمصمم المصنف. يؤدي هذا إلى تكرار المنطق، وتعقيد نماذج البيانات، وزيادة احتمال الأخطاء. تلغي سمتا ArrayAsSingle وExtraDelimiter هذا الحل البديل من خلال معالجة التنسيق بشكل وصفي داخل العلامة الذكية نفسها.

فوائد الميزة

يوفر استخدام سمتي ArrayAsSingle وExtraDelimiter في العلامات الذكية العديد من المزايا:

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

كيفية استخدام هذه الميزة

صيغة العلامة الذكية

يتم تمرير سمتي ArrayAsSingle وExtraDelimiter كأزواج مفتاح-قيمة داخل أقواس علامة ذكية قياسية. الصيغة العامة هي:

&=DataSource.ArrayProperty(arrayasSingle=true, extraDelimiter=", ")

تتكون العلامة من الأجزاء التالية:

&=DataSource.ArrayProperty — العلامة الذكية القياسية التي تشير إلى خاصية المصفوفة في مصدر البيانات المرتبط.
arrayasSingle=true — يوجه المحرك لعرض المصفوفة بأكملها في خلية واحدة. فقط القيمة true تؤدي إلى سلوك الخلية الواحدة.
extraDelimiter=", " — يحدد الفاصل الموضوع بين عناصر المصفوفة. القيمة هي سلسلة حرفية؛ يمكن أن تكون فارغة أو حرفًا واحدًا أو سلسلة متعددة الأحرف.

تقبل سمة extraDelimiter أي سلسلة حرفية، بما في ذلك الفواصل متعددة الأحرف أو النص المخصص أو تسلسلات الهروب مثل \n للإخراج المفصول بسطر جديد. إذا كانت المصفوفة فارغة، تُترك الخلية الناتجة فارغة.

سير العمل خطوة بخطوة

يصف سير العمل التالي كيفية عرض مصفوفة في خلية واحدة باستخدام العلامات الذكية.

تجهيز مصدر البيانات: أنشئ فئة (أو بنية بيانات) تعرض خاصية تُرجع مصفوفة. يمكن للخاصية إرجاع list[str] أو list[int] أو أي نوع مصفوفة مدعوم آخر.
إنشاء مصنف مصمم: أنشئ Workbook جديدًا، وأضف صف ترويسة، وضع خلية علامة ذكية تشير إلى خاصية المصفوفة مع سمتي arrayasSingle وextraDelimiter.
إنشاء مثيل WorkbookDesigner: أنشئ كائن WorkbookDesigner، واربط مصنف المصمم به، واربط مصدر البيانات الخاص بك باستخدام طريقة set_data_source.
معالجة العلامات: استدعِ طريقة WorkbookDesigner.process() لتوسيع العلامات الذكية وتعبئة المصنف ببيانات حقيقية.
حفظ النتيجة: احفظ المصنف الناتج على القرص بتنسيق XLSX أو أي تنسيق ملف آخر مدعوم.

مثال الكود 1 — عرض مصفوفة سلسلة نصية أساسية

class Product:
    def __init__(self):
        self.Tags = []

product = Product()
product.Tags = ["C#", "Aspose", "SmartMarker", "Excel"]

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

worksheet.cells["A1"].put_value("Tags")
worksheet.cells["A2"].put_value("&=Product.Tags(arrayasSingle=true, extraDelimiter=\", \")")

designer = ac.WorkbookDesigner()
designer.workbook = workbook
designer.set_data_source("Product", product)
designer.process()

workbook.save("output_arraySingle.xlsx")

مثال الكود 2 — مصفوفة رقمية مع فاصل مخصص

class Student:
    def __init__(self):
        self.scores = []


student = Student()
student.scores = [95, 88, 76, 100, 67]

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

worksheet.cells["A1"].put_value("Scores")
worksheet.cells["A2"].put_value(" - ".join(str(s) for s in student.scores))

workbook.save("output_numericArray.xlsx")

مثال الكود 3 — مقارنة السلوك الافتراضي مقابل ArrayAsSingle

class Order:
    def __init__(self, items):
        self._items = items

    @property
    def Items(self):
        return self._items

    @Items.setter
    def Items(self, value):
        self._items = value

order = Order(["Apple", "Banana", "Cherry", "Date"])

workbook = ac.Workbook()
sheet = workbook.worksheets[0]
cells = sheet.cells

# القسم 1: العلامة الذكية الافتراضية - القيم تنتشر أفقيًا عبر الخلايا
cells["A1"].put_value("Default Spreading Behavior:")
cells["A2"].put_value("&=Order.Items")

# القسم 2: عرض الخلية الواحدة الجديد باستخدام arrayasSingle و extraDelimiter
cells["A4"].put_value("Single Cell Rendering (arrayasSingle=true):")
cells["A5"].put_value('&=Order.Items(arrayasSingle=true, extraDelimiter="; ")')

# ربط مصدر البيانات ومعالجة العلامات الذكية
designer = ac.WorkbookDesigner(workbook)
designer.set_data_source("Order", order)
designer.process()

# حفظ المصنف الناتج
workbook.save("output_comparison.xlsx")

ملاحظات وأفضل الممارسات

ضع النقاط التالية في اعتبارك عند العمل مع سمتي ArrayAsSingle وExtraDelimiter:

تُعامل قيمة extraDelimiter كسلسلة حرفية؛ قم بإفلات أي أحرف خاصة قد يفسرها معالج القالب الخاص بك.
تقبل سمة arrayasSingle قيمة منطقية (True / False). فقط True تؤدي إلى سلوك الخلية الواحدة؛ أي قيمة أخرى تعود إلى سلوك الانتشار الافتراضي.
إذا كانت المصفوفة فارغة أو لا شيء، تُترك الخلية فارغة (أو تحتوي على سلسلة فارغة حسب نوع البيانات).
تعمل الميزة مع مصادر بيانات الكائنات وكذلك مصادر DataSet وDataTable حيث يمكن تقسيم عمود إلى مصفوفات.
للإخراج المفصول بسطر جديد، يمكنك استخدام \n أو os.linesep كقيمة فاصل.
ضع العلامة الذكية في خلية ذات عرض كافٍ لعرض السلسلة المتسلسلة الناتجة؛ وإلا، قد يفيض المحتوى بصريًا إلى الخلايا المجاورة حسب التنسيق.