كيفية العمل مع الجداول في .NET
هذا الدليل يوضح كيفية بناء وتنسيق وقراءة الجداول برمجياً في Aspose.Words FOSS لـ .NET, باستخدام الـ Table, Row, و Cell الفئات في الـ Aspose.Words.Tables النطاق مع DocumentBuilder. يغطي إنشاء جدول من الصفر، وتنسيق الخلايا والصفوف أثناء الإنشاء، والتحكم في تخطيط الجدول بالكامل و AutoFit، وتحديد العرض المفضل، ودمج الخلايا، وقراءة الجداول الموجودة بالفعل في مستند محمَّل.
دليل خطوة بخطوة
الخطوة 1: تثبيت الحزمة
Aspose.Words FOSS for .NET لم تنشر بعد حزمة NuGet – قم ببناء المكتبة من المصدر بدلاً من ذلك. استنسخ https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git، ثم ابنِ Aspose.Words.sln في تكوين Release باستخدام مجموعة تطوير .NET SDK واستشهد بتجميع Aspose.Words الناتج من مشروعك. تستهدف المكتبة .NET Standard 2.0، لذا تعمل على .NET Framework 4.6.2+ و.NET 6/8/10.
الخطوة 2: استيراد الفئات المطلوبة
أضف توجيه using Aspose.Words; للفئات الأساسية للمستند (Document، DocumentBuilder)، وتوجيه using Aspose.Words.Tables; للفئات الخاصة بالجداول التي يغطيها هذا الدليل – Table، Row، Cell، CellFormat، RowFormat، PreferredWidth، والـ enums المرتبطة.
الخطوة 3: إنشاء جدول جديد باستخدام DocumentBuilder
أنشئ Document وDocumentBuilder مرتبطين به، ثم استدعِ DocumentBuilder.StartTable() لبدء جدول عند المؤشر. لكل خلية في صف، استدعِ DocumentBuilder.InsertCell()، ثم أغلق الصف باستخدام DocumentBuilder.EndRow(). كرّر ذلك للعدد المطلوب من الصفوف التي يحتاجها الجدول، وأغلق الجدول بالكامل باستخدام DocumentBuilder.EndTable(). كل StartTable() يحتاج إلى EndTable() مطابق، وكل صف يحتاج إلى EndRow() مطابق، وإلا ستصبح الحالة الداخلية للمنشئ — وشجرة المستند الناتجة — مشوهة.
الخطوة 4: تنسيق الخلايا والصفوف أثناء الإنشاء
قم بتعيين DocumentBuilder.CellFormat وDocumentBuilder.RowFormat قبل استدعاء InsertCell() أو EndRow() لتطبيق التنسيق على الخلايا والصفوف التي على وشك إنشائها بواسطة المنشئ — هذان الخصائص يعملان كقالب للمحتوى الجديد، وليس كتحويل رجعي للخلايا التي أُدخلت بالفعل. يوضح CellFormat Borders، Shading، Width، WrapText، FitText، HorizontalMerge، VerticalMerge، VerticalAlignment، PreferredWidth، بالإضافة إلى خصائص الحشو الأربعة (LeftPadding، RightPadding، TopPadding، BottomPadding)، والتي يمكن تعيينها جميعًا مرة واحدة باستخدام SetPaddings(). يوضح RowFormat Borders، Height، HeightRule، AllowBreakAcrossPages، وHeadingFormat. استدعِ CellFormat.ClearFormatting() أو RowFormat.ClearFormatting() لإعادة تعيين أي منهما إلى القيم الافتراضية قبل تعيين قيم جديدة للصف أو الخلية التالية.
الخطوة 5: تعيين تخطيط الجدول بالكامل و AutoFit
بعد وجود الجدول، عيّن خصائص التخطيط مباشرةً على كائن Table: Alignment (TableAlignment)، Bidi، LeftIndent، PreferredWidth، Style، StyleIdentifier، StyleName، StyleOptions (TableStyleOptions)، وTextWrapping. استدعِ Table.SetBorders() لتطبيق نمط حد واحد، عرض، ولون عبر كامل الجدول، أو Table.SetBorder() لتعيين جانب واحد؛ ClearBorders() وClearShading() تعيدان ضبطهما. يقوم Table.AutoFit(AutoFitBehavior) بتغيير حجم الجدول وخلاياه وفق السلوك المختار — استدعِه مرة أخرى بعد أي تعديل هيكلي، لأنه يعكس حالة الجدول فقط في اللحظة التي يُنفّذ فيها، وليس بشكل مستمر.
الخطوة 6: تعيين العرض المفضل وعرض الخلايا
أنشئ قيم العرض باستخدام طرق المصنع الثابتة PreferredWidth.FromPercent() لتخطيط يتكيف مع عرض الصفحة المتاح، أو PreferredWidth.FromPoints() لعرض ثابت؛ PreferredWidthType يبلّغ أي نوع من القيم (Auto، Percent، أو Points) يحملها PreferredWidth معين. عيّن النتيجة إما إلى Table.PreferredWidth للجدول بأكمله أو إلى CellFormat.PreferredWidth لخلية واحدة.
الخطوة 7: دمج الخلايا
ضع علامة دمج الخلايا عن طريق ضبط CellFormat.HorizontalMerge أو CellFormat.VerticalMerge (كلاهما مكتوب CellMerge) على الخلايا التي يجب أن تشارك في الدمج. إذا تم جعل الخلايا تبدو كأنها مدمجة فقط من خلال مطابقة عرضها بدلاً من وضع علامة صريحة، استدعِ Table.ConvertToHorizontallyMergedCells() لتحويل ذلك الترتيب البصري إلى خلايا ذات حالة CellMerge حقيقية. CellVerticalAlignment يتحكم في كيفية ضبط المحتوى عمودياً داخل الخلية، بغض النظر عن أي دمج.
الخطوة 8: قراءة الجداول من مستند موجود
للعمل مع الجداول الموجودة بالفعل في مستند محمّل، اقرأ Body.Tables (أو خاصية Tables على أي Story آخر) — TableCollection — بدلاً من إنشاء جداول جديدة. Table.Rows يُعيد RowCollection وRow.Cells يُعيد CellCollection؛ جميع أنواع المجموعات الثلاث تدعم Add()، Insert()، Remove()، RemoveAt()، Contains()، وIndexOf() للتعديلات البرمجية. بعد إزالة الصفوف أو الخلايا، استدعِ Table.EnsureMinimum() أو Row.EnsureMinimum() أو Cell.EnsureMinimum() بحيث يحتفظ العقدة بالحد الأدنى من البنية الصالحة التي يتوقعها Word — صف فارغ، خلية فارغة، أو فقرة فارغة، على التوالي.
المشكلات الشائعة والحلول
يبدو المستند المحفوظ مشوّهًا، أو يحدث خطأ أثناء الحفظ لم يتم إغلاق صف أو الجدول نفسه أبداً. يجب دائمًا إقران DocumentBuilder.StartTable() مع نهائي EndTable()، وأغلق كل صف بـ EndRow() قبل الانتقال إلى التالي أو إنهاء الجدول.
الخلايا الجديدة لا تستقبل التنسيق الذي حددته CellFormat and RowFormat تم تغييرها على DocumentBuilder بعد إدراج الخلايا المتأثرة بالفعل. اضبط DocumentBuilder.CellFormat / RowFormat قبل الـ InsertCell() or EndRow() استدعاء ينشئ المحتوى الذي تريد تنسيقه.
الجدول لا يعيد حجمه كما أتوقع بعد تعديل محتواه Table.AutoFit(AutoFitBehavior) يعكس بنية الجدول فقط في اللحظة التي يُستدعى فيها. استدعِه مرة أخرى بعد أي تعديل هيكلي — إضافة أو حذف صفوف أو خلايا أو محتوى — إذا كان التخطيط بحاجة إلى إعادة ضبط.
الخلايا التي تبدو مدمجة تتصرف كخلايا منفصلة عند قراءتها مرة أخرى تم مطابقة الخلايا حسب العرض فقط، دون الإشارة إليها بـ CellMerge. استدعِ Table.ConvertToHorizontallyMergedCells(), أو اضبط CellFormat.HorizontalMerge / VerticalMerge بشكل صريح على الخلايا التي يجب دمجها.
إزالة الصفوف أو الخلايا يترك الجدول في حالة غير صالحة Word يتوقع كل Table, Row, و Cell للحفاظ على بنية صالحة على الأقل. بعد إزالة المحتوى برمجيًا، استدعِ EnsureMinimum() على العقدة التي تم تعديلها للتو.
الأسئلة المتكررة
كيف يمكنني إنشاء جدول من الصفر بدلاً من تعديل جدول موجود؟
استخدم DocumentBuilder: استدعِ StartTable()، ثم InsertCell() لكل خلية في صف، EndRow() لإغلاق الصف، كرّر للصفوف الإضافية، وEndTable() لإغلاق الجدول.
كيف أحصل على الجداول الموجودة بالفعل في مستند محمَّل؟
اقرأ خاصية Tables (وهي TableCollection) على Body للقسم الذي تهتم به، أو على أي Story أخرى مثل الرأس أو التذييل.
كيف يمكنني ضبط جدول ليكون بنسبة مئوية من عرض الصفحة بدلاً من عرض ثابت؟
عيّن Table.PreferredWidth = PreferredWidth.FromPercent(value) بدلاً من PreferredWidth.FromPoints(value).
ما الفرق بين ضبط الحدود باستخدام SetBorders و SetBorder؟
Table.SetBorders() يطبق نمط خط واحد وعرض ولون على كل حد في الجدول دفعة واحدة؛ Table.SetBorder() يحدد جانبًا واحدًا، مما يسمح للأطراف المختلفة بحمل تنسيق مختلف.
كيف يمكنني إعادة ضبط التنسيق على خلية أو صف قبل إعادة استخدامها؟
استدعِ CellFormat.ClearFormatting() على CellFormat للخلية، أو RowFormat.ClearFormatting() على RowFormat للصف.
