عرض مصفوفة خلية واحدة في SmartMarker | Aspose.Cells Java

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

مقدمة

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

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

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

لماذا هذه الميزة مطلوبة

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

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

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

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

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

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

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

فوائد الميزة

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

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

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

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

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

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

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

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

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

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

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

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

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

import com.aspose.cells.*;

class Product {
    public String[] Tags;
}

public class CodeRunner {
    public static void main(String[] args) throws Exception {
        Product product = new Product();
        product.Tags = new String[] { "C#", "Aspose", "SmartMarker", "Excel" };

        Workbook workbook = new Workbook();
        Worksheet worksheet = workbook.getWorksheets().get(0);

        worksheet.getCells().get("A1").putValue("Tags");
        worksheet.getCells().get("A2").putValue("&=Product.Tags(arrayasSingle=true, extraDelimiter=\", \")");

        WorkbookDesigner designer = new WorkbookDesigner();
        designer.setWorkbook(workbook);
        designer.setDataSource("Product", product);
        designer.process();

        workbook.save("output_arraySingle.xlsx");
    }
}

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

import com.aspose.cells.*;

class Student
{
    public int[] Scores;
}

public class CodeRunner
{
    public static void main(String[] args) throws Exception
    {
        Student student = new Student();
        student.Scores = new int[] { 95, 88, 76, 100, 67 };

        Workbook workbook = new Workbook();
        Worksheet worksheet = workbook.getWorksheets().get(0);

        worksheet.getCells().get("A1").putValue("Scores");

        StringBuilder joined = new StringBuilder();
        for (int i = 0; i < student.Scores.length; i++)
        {
            if (i > 0) joined.append(" - ");
            joined.append(student.Scores[i]);
        }
        worksheet.getCells().get("A2").putValue(joined.toString());

        workbook.save("output_numericArray.xlsx");
    }
}

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

class Order
{
    private String[] items;

    public String[] getItems()
    {
        return items;
    }

    public void setItems(String[] items)
    {
        this.items = items;
    }
}

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

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

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