العمل مع الجداول
العمل مع الجداول
الجداول في Aspose.Words FOSS لـ .NET مُمثلة بـ Aspose.Words.Tables المساحة الاسمية: Table, Row, و Cell تشكل هيكلية عقد مركبة من ثلاثة مستويات تجلس في شجرة المستند إلى جانب الفقرات. تغطي هذه الصفحة بناء الجداول باستخدام DocumentBuilder, تنسيق الصفوف والخلايا، التحكم في تخطيط الجدول بالكامل، ودمج الخلايا.
نموذج كائن الجدول
Table هو CompositeNode يحتوي على عقد Row، وكل Row هو CompositeNode يحتوي على عقد Cell؛ Cell بدوره يحتوي على فقرات وربما جداول متداخلة. يُعيد Table.Rows RowCollection، ويُعيد Row.Cells CellCollection، وBody أو Story آخر يكشف كل جدول من المستوى الأعلى فيه عبر خاصية Tables الخاصة به، وهي TableCollection. تدعم المجموعات الثلاثة جميعًا Add()، Insert()، Remove()، RemoveAt()، Contains()، وIndexOf(). يملأ كل من Table.EnsureMinimum() وRow.EnsureMinimum() وCell.EnsureMinimum() أصغر محتوى صالح يحتاجه عقدة من هذا النوع (صف فارغ، خلية فارغة، أو فقرة فارغة، على التوالي) بعد أن تترك التعديلات البرمجية أحدها بدون ذلك.
بناء جداول باستخدام DocumentBuilder
DocumentBuilder.StartTable() يبدأ جدولًا جديدًا عند المؤشر، InsertCell() يضيف خلية إلى الصف الحالي، EndRow() يغلق الصف الحالي، وEndTable() يغلق الجدول. قم بتعيين DocumentBuilder.CellFormat وDocumentBuilder.RowFormat قبل استدعاء InsertCell() أو EndRow() لتطبيق التنسيق الافتراضي على الخلايا والصفوف عند إنشائها — هذه الخصائص تعمل كقالب للمحتوى الذي يضيفه المُنشئ بعد ذلك، وليس كتغيير رجعي على الخلايا الموجودة بالفعل في المستند.
تنسيق الخلية والصف
Cell.CellFormat هو كائن CellFormat (Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth, LeftPadding, RightPadding, TopPadding, BottomPadding, HideMark, Orientation) مع ClearFormatting() لإعادة تعيينه و SetPaddings() لتعيين جميع حشوات الخلايا الأربعة مرة واحدة. Row.RowFormat هو كائن RowFormat (Borders, Height, HeightRule, AllowBreakAcrossPages, HeadingFormat) له ClearFormatting() الخاص به.
تنسيق على مستوى الجدول و AutoFit
Table نفسه يكشف عن خصائص التخطيط – Alignment (TableAlignment)، Bidi، LeftIndent، PreferredWidth، Style، StyleIdentifier، StyleName، StyleOptions (TableStyleOptions)، TextWrapping، وبيانات التعريف الخاصة بإمكانية الوصول عبر Title وDescription. Table.AutoFit(AutoFitBehavior) يغيّر حجم الجدول وخلاياه وفقًا للسلوك المحدد. SetBorder() يحدد جانبًا واحدًا من الحدود وSetBorders() يحدد جميع الحدود بنفس نمط الخط والعرض واللون عبر الجدول بأكمله؛ ClearBorders() وClearShading() يعيدان تعيينها. ConvertToHorizontallyMergedCells() يحول الخلايا التي تم دمجها بتطابق العرض إلى خلايا يتم تعليمها صراحةً بـ HorizontalMerge.
العرض المفضل وعرض الخلايا
PreferredWidth يمثل عرضًا ووحدته، تم إنشاؤه باستخدام طرق المصنع الثابتة PreferredWidth.FromPercent() أو PreferredWidth.FromPoints(); PreferredWidthType يحدد أي نوع من القيم (Auto، Percent أو Points) يحملها PreferredWidth معين. كلا من Table.PreferredWidth وCellFormat.PreferredWidth يقبلان هذه القيم.
الخلايا المدمجة
CellFormat.HorizontalMerge وCellFormat.VerticalMerge (CellMerge) يحددان كيفية مشاركة خلية في دمج أفقي أو رأسي مع جيرانها. CellVerticalAlignment يتحكم في محاذاة المحتوى داخل الخلية عموديًا، بغض النظر عن حالة الدمج.
نصائح وأفضل الممارسات
- أغلق كل
StartTable()بـEndRow()مطابقة لكل صف وEndTable()نهائي — ترك صف أو جدول غير مغلق يترك حالة داخلية للمنشئ (وشجرة المستند الناتجة) غير صحيحة. - قم بتعيين
DocumentBuilder.CellFormatوDocumentBuilder.RowFormatقبل كل استدعاءInsertCell()أوEndRow()إذا كانت الصفوف أو الخلايا المختلفة في نفس الجدول تحتاج إلى تنسيق مختلف؛ يقوم المُنشئ بتطبيق ما تم تعيينه في لحظة الإدراج. - استدعِ
Table.EnsureMinimum()أوRow.EnsureMinimum()أوCell.EnsureMinimum()بعد إزالة المحتوى برمجياً حتى يبقى العقدة بأقل بنية صالحة يتوقعها Word. - استخدم
PreferredWidth.FromPercent()للجداول التي يجب أن تتكيف مع عرض الصفحة المتاح، وPreferredWidth.FromPoints()لعرض تخطيط ثابت. AutoFitBehaviorيتم تطبيقه عندما تستدعيTable.AutoFit()— لا يعاد تشغيله بشكل مستمر أثناء إضافة أو إزالة المحتوى، لذا استدعِه مرة أخرى بعد التعديلات الكبيرة إذا كنت بحاجة إلى إعادة ضبط حجم الجدول.
المشكلات الشائعة
| مشكلة | السبب | إصلاح |
|---|---|---|
| الجدول يبدو مشوهاً أو يسبب خطأ عند الحفظ | لم يتم إغلاق صف أو الجدول أبداً باستخدام EndRow() / EndTable() | دائمًا اجمع بين StartTable() مع EndTable() النهائي، وأغلق كل صف باستخدام EndRow() |
| الخلايا الجديدة لا تتبنى التنسيق الذي قمت بتعيينه | تم تغيير CellFormat / RowFormat في المُنشئ بعد إدخال الخلايا بالفعل | قم بتعيين DocumentBuilder.CellFormat / RowFormat قبل استدعاء InsertCell() / EndRow() لهذا المحتوى |
| الجدول لا يُعيد التحجيم كما أتوقع بعد التعديلات | AutoFit() يعكس حالة الجدول في اللحظة التي يُستدعى فيها، وليس بشكل مستمر | استدعِ Table.AutoFit(AutoFitBehavior) مرة أخرى بعد التعديلات الهيكلية |
| الخلايا المتجاورة التي تبدو مدمجة تتصرف كخلايا منفصلة | تم مطابقة الخلايا فقط حسب العرض، ولم يتم وضع علامة عليها بـ CellMerge | استدعِ Table.ConvertToHorizontallyMergedCells()، أو اضبط CellFormat.HorizontalMerge / VerticalMerge صراحةً |
FAQ
كيف يمكنني إنشاء جدول من الصفر باستخدام DocumentBuilder؟
استدعِ StartTable()، ثم InsertCell() لكل خلية في الصف، EndRow() لإغلاق الصف، كرّر للصفوف الإضافية، وأخيرًا EndTable() لإغلاق الجدول.
كيف يمكنني ضبط عرض الجدول كنسبة مئوية بدلاً من عرض ثابت؟
عيّن Table.PreferredWidth = PreferredWidth.FromPercent(value) بدلاً من PreferredWidth.FromPoints(value).
كيف يمكنني إعادة تعيين جميع التنسيقات على خلية أو صف؟
استدعِ CellFormat.ClearFormatting() على CellFormat للخلية، أو RowFormat.ClearFormatting() على RowFormat للصف.
كيف يمكنني ضبط الحدود والتظليل للجدول بأكمله مرة واحدة؟
استخدم Table.SetBorders() للحصول على حد موحد على جميع الجوانب، وTable.SetBorder() لجانب واحد في كل مرة، وTable.SetShading() لتظليل موحد؛ ClearBorders() وClearShading() لإعادة ضبطهما.
API Reference ملخص
| فئة / تعداد | وصف |
|---|---|
Table | عقدة الجدول؛ Rows، AutoFit()، SetBorders()، SetShading()، PreferredWidth |
Row | عقدة صف الجدول؛ Cells، RowFormat، EnsureMinimum() |
Cell | عقدة خلية الجدول؛ CellFormat, EnsureMinimum() |
TableCollection / RowCollection / CellCollection | مجموعات ذات نوع من عقد Table / Row / Cell |
CellFormat | تنسيق لكل خلية: الحدود، التظليل، الحشوة، حالة الدمج، المحاذاة العمودية |
RowFormat | تنسيق لكل صف: الحدود، الارتفاع، سلوك فاصل الصفحات |
PreferredWidth / PreferredWidthType | قيمة عرض الجدول أو الخلية ووحدتها (auto, percent, points) |
AutoFitBehavior | كيف يقوم Table.AutoFit() بتغيير حجم جدول وخلاياه |
CellMerge / CellVerticalAlignment | حالة دمج الخلايا أفقياً/عمودياً ومحاذاة المحتوى عمودياً |
TableAlignment / TableStyleOptions / TextWrapping | محاذاة على مستوى الجدول، تطبيق النمط، وسلوك التفاف النص |
DocumentBuilder.StartTable / InsertCell / EndRow / EndTable | إنشاء جدول قائم على المؤشر |
