العمل مع القوائم

العمل مع القوائم

يوضح هذا الدليل كيفية تمثيل القوائم المرقمة والقوائم النقطية والتحكم فيها في Aspose.Words FOSS لـ .NET. List هو تعريف قائمة قابل لإعادة الاستخدام يُشارك بين كل فقرة تستخدمه، ListFormat هو الطريقة التي تشير بها فقرة فردية إلى قائمة ومستواها الحالي، وListLevel يحتفظ بالتنسيق الفعلي للترقيم أو النقاط لمستوى واحد من القائمة.

كائن القائمة و ListCollection

List يمثل تعريف قائمة واحدة — قواعد الترقيم التي يمكن للمستند تطبيقها على العديد من الفقرات. List.ListId يحددها، List.IsMultiLevel يُبلغ عما إذا كانت تعرف أكثر من مستوى واحد، وList.ListLevels يُعيد ListLevelCollection يحتوي على ListLevel واحد لكل مستوى تُعرّفه القائمة. List.IsListStyleDefinition وIsListStyleReference يميزان القائمة التي تُعرّف تنسيقها الخاص عن تلك التي تُشير إلى التنسيق عبر Style مرتبط (متاح عبر List.Style). تُوصل قوائم كل مستند عبر Document.Lists، التي تُعيد ListCollection: ListCollection.Add(listTemplate) يُنشئ قائمة جديدة من أحد تنسيقات ListTemplate المُعرّفة مسبقًا في Word، Add(listStyle) يُنشئ واحدة من Style, AddSingleLevelList(listTemplate) يُنشئ نسخة ذات مستوى واحد، وAddCopy(srcList) يكرر قائمة موجودة — مفيد عندما تريد أن تكون الفقرات ذات ترقيم مستقل (إعادة تشغيل جديدة) بدلاً من مشاركة نفس العداد. ListCollection.GetListByListId(listId) يسترجع قائمة محددة، وCount يُبلغ عن عدد القوائم التي يمتلكها المستند.

تطبيق القوائم على الفقرات باستخدام ListFormat

ListFormat، الذي يُسترجع من تنسيق الفقرة، يتحكم في القائمة التي تنتمي إليها الفقرة وعلى أي مستوى. ListFormat.List هو الـ List الذي تستخدمه الفقرة، وListFormat.ListLevelNumber هو المستوى الصفري داخل تلك القائمة؛ IsListItem يُبلغ عما إذا كانت الفقرة جزءًا من قائمة على الإطلاق. ApplyBulletDefault() وApplyNumberDefault() يطبقان تنسيق القائمة النقطية أو المرقمة الافتراضي في Word على الفقرة في نداء واحد، RemoveNumbers() يزيل تنسيق القائمة، وListIndent()/ListOutdent() ينقلان الفقرة إلى مستوى أعمق أو أقل داخل مستويات القائمة — نفس العمليات التي ينفذها Word عند الضغط على Tab أو Shift+Tab في بداية فقرة قائمة.

مستويات القائمة ونمط الترقيم

ListLevel يحتفظ بالتنسيق لمستوى واحد من القائمة: NumberStyle (قيمة تعداد NumberStyle مثل الأرقام العربية أو الأرقام الرومانية)، NumberFormat (سلسلة التنسيق التي تجمع الرقم مع النص الحرفي، مثل نقطة أو قوس)، StartAt (رقم البداية)، و RestartAfterLevel (أي مستوى أعلى يعيد تشغيل عداد هذا المستوى). Alignment (قيمة ListLevelAlignment: Left، Center، Right) و TrailingCharacter (قيمة ListTrailingCharacter: Tab، Space، Nothing) تتحكم في موضع التسمية وفصلها عن نص الفقرة، إلى جانب TabPosition، NumberPosition، و TextPosition لتخطيط دقيق. IsLegal يفرض ترقيمًا على الطراز القانوني (دائمًا عربي، بغض النظر عن NumberStyle)، و LinkedStyle يربط المستوى بStyle الفقرة. بالنسبة للترقيم بالصور، CreatePictureBullet() و DeletePictureBullet() يديران صورة ترقيم ImageData، و ListLevel.Font يحدد تنسيق الرقم أو حرف الترقيم نفسه. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) يحسب القيمة الفعلية للعلامة في موضع معين في تسلسل الترقيم.

تسميات القوائم والقوالب المعرفة مسبقًا

ListLabel يصف التسمية المعروضة لمثال عنصر قائمة محدد — LabelString هو النص الحرفي الذي يعرضه Word (مثل “3.” أو “•")، LabelValue هو القيمة الرقمية الأساسية، و Font هو تنسيق التسمية. ListTemplate هو تعداد لتنسيقات القوائم المعرفة مسبقًا في Word (أنماط الرصاص مثل BulletDefault، BulletDisk، BulletCircle، BulletSquare، BulletDiamonds، وتنسيقات مرقمة)، يُستخدم مع ListCollection.Add(listTemplate) للبدء من تنسيق مدمج بدلاً من بناء خاصية واحدة تلو الأخرى.

نصائح وأفضل الممارسات

• استخدم ListCollection.AddCopy(srcList) عندما تحتاج مجموعة جديدة من الفقرات إلى ترقيم قائمة يبدأ من جديد بشكل مستقل، بدلاً من إعادة استخدام List المرتبط بالفعل بفقرات أخرى.
• فضل استخدام ListFormat.ApplyNumberDefault() / ApplyBulletDefault() للقوائم القياسية بدلاً من ضبط كل خاصية ListLevel يدويًا.
• تحقق من List.IsListStyleReference مقابل IsListStyleDefinition قبل تعديل تنسيق القائمة مباشرةً — قد يتم التحكم في تنسيق قائمة تشير إلى نمط بواسطة Style المرتبط بها بدلاً من ذلك.
• قم بتعيين RestartAfterLevel صراحةً على القوائم المتداخلة بدلاً من الاعتماد على سلوك إعادة التشغيل الافتراضي عندما يجب إعادة ضبط الترقيم في مستويات المخطط المحددة.
• استخدم ListFormat.ListIndent()/ListOutdent() لنقل فقرة بين مستويات القوائم بدلاً من ضبط ListLevelNumber مباشرةً، لأن هذه الطرق تحافظ على تنسيق قائمة الفقرة متسقًا داخليًا.

مشكلات شائعة

FAQ

ما الفرق بين List و ListFormat؟

List هو تعريف الترقيم/النقطة القابل لإعادة الاستخدام المشترك بين الفقرات؛ ListFormat هو لكل فقرة — يشير إلى أي List تستخدمه الفقرة المحددة وإلى أي مستوى، عبر ListFormat.List و ListLevelNumber.

كيف يمكنني التحقق مما إذا كانت الفقرة جزءًا من قائمة؟

اطّلع على ListFormat.IsListItem بخصوص تنسيق الفقرة؛ إذا كان true، فإن ListFormat.List و ListLevelNumber يصفان أي قائمة وأي مستوى تنتمي إليه.

كيف أجعل قائمة جديدة تبدأ الترقيم من 1 بشكل مستقل عن القائمة الحالية؟

استخدم ListCollection.AddCopy(srcList) لإنشاء نسخة مستقلة من تعريف القائمة، ثم طبّق النسخة على الفقرات الجديدة — بدلاً من إعادة استخدام List الأصلي، الذي سيستمر في نفس العداد.

كيف يمكنني إنشاء قائمة نقطية أو مرقمة من الصفر؟

استخدم ListFormat.ApplyBulletDefault() أو ApplyNumberDefault() لتنسيق Word الافتراضي، أو ListCollection.Add(listTemplate) مع قيمة ListTemplate للبدء من أحد التنسيقات المعرّفة مسبقًا في Word وتخصيص الـ List.ListLevels الناتج من هناك.

كيف يمكنني التحكم في تنسيق الرقم، مثل “1)” بدلاً من “1."؟

عيّن ListLevel.NumberFormat على المستوى المناسب إلى سلسلة التنسيق المطلوبة، إلى جانب NumberStyle لتحديد نمط الرقم نفسه.

API Reference ملخص

انظر أيضاً

• Aspose.Words for .NET — Enterprise Documentation