کار با لیست‌ها
کار با فهرست‌ها
این راهنما نشان می‌دهد که فهرست‌های شماره‌دار و با گلوله چگونه در 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 ورد ایجاد می‌کند، Add(listStyle) یک فهرست از یک Style می‌سازد، AddSingleLevelList(listTemplate) یک گونهٔ تک‌سطحی ایجاد می‌کند، و AddCopy(srcList) یک فهرست موجود را تکرار می‌کند — که زمانی مفید است که می‌خواهید پاراگراف‌ها شماره‌گذاری مستقل داشته باشند (شروع تازه) به‌جای اشتراک‌گذاری همان شمارنده. ListCollection.GetListByListId(listId) یک فهرست خاص را بازیابی می‌کند، و Count گزارش می‌دهد که سند چند فهرست دارد.
اعمال فهرست‌ها به پاراگراف‌ها با ListFormat
ListFormat که از قالب‌بندی پاراگراف قابل دسترسی است، تعیین می‌کند پاراگراف به چه فهرستی تعلق دارد و در چه سطحی قرار دارد. ListFormat.List List ای است که پاراگراف استفاده می‌کند، و ListFormat.ListLevelNumber سطح صفر-مبنا داخل آن فهرست است؛ IsListItem گزارش می‌دهد که آیا پاراگراف به‌طور کلی بخشی از فهرست است یا نه. ApplyBulletDefault() و ApplyNumberDefault() قالب‌بندی پیش‌فرض گلوله‌ای یا شماره‌دار ورد را در یک فراخوانی به پاراگراف اعمال می‌کنند، RemoveNumbers() قالب‌بندی فهرست را حذف می‌کند، و ListIndent()/ListOutdent() پاراگراف را به سطحی عمیق‌تر یا سطحی کم‌عمق‌تر در فهرست منتقل می‌کنند — همان عملیاتی که ورد هنگام فشار دادن Tab یا Shift+Tab در ابتدای یک پاراگراف فهرست انجام می‌دهد.
سطوح فهرست و سبک شماره‌گذاری
ListLevel قالب‌بندی یک سطح از لیست را نگه می‌دارد: NumberStyle (یک مقدار enum 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 متن صریحی است که ورد نمایش می‌دهد (مانند «3.» یا «•»)، LabelValue مقدار عددی زیرین است، و Font قالب‌بندی برچسب است. ListTemplate یک enum از قالب‌های پیش‌تعریف‌شده فهرست در ورد است (سبک‌های گلوله‌ای مانند BulletDefault، BulletDisk، BulletCircle، BulletSquare، BulletDiamonds و قالب‌های عددی)، که با ListCollection.Add(listTemplate) برای شروع از یک قالب داخلی به‌جای ساخت هر ویژگی به‌صورت جداگانه استفاده می‌شود.
نکات و بهترین روش‌ها
- از
ListCollection.AddCopy(srcList)استفاده کنید وقتی یک گروه جدید از پاراگراف‌ها به شماره‌گذاری فهرست نیاز دارد که به‌صورت مستقل از نو شروع شود، به‌جای استفاده مجدد ازListکه قبلاً به سایر پاراگراف‌ها متصل شده است. - به جای پیکربندی دستی هر ویژگی
ListLevel، برای فهرست‌های استانداردListFormat.ApplyNumberDefault()/ApplyBulletDefault()را ترجیح دهید. - قبل از تغییر مستقیم قالب‌بندی فهرست،
List.IsListStyleReferenceدر مقابلIsListStyleDefinitionرا بررسی کنید — قالب‌بندی فهرستی که به یک سبک ارجاع می‌دهد ممکن است به‌جای آن توسطStyleمرتبط آن کنترل شود. - در فهرست‌های تو در تو،
RestartAfterLevelرا به‌صورت صریح تنظیم کنید به‌جای این‌که به رفتار پیش‌فرض بازنشانی وابسته باشید وقتی شماره‌گذاری باید در سطوح خاصی از طرح بندی بازنشانی شود. - از
ListFormat.ListIndent()/ListOutdent()برای جابجایی یک پاراگراف بین سطوح فهرست استفاده کنید به جای تنظیم مستقیمListLevelNumber، زیرا این روش‌ها قالب‌بندی فهرست پاراگراف را به‌صورت داخلی سازگار نگه می‌دارند.
مشکلات رایج
| مسئله | دلیل | رفع |
|---|---|---|
| دو پاراگراف که باید به‌صورت مستقل شماره‌گذاری شوند، همان توالی را ادامه می‌دهند | هر دو پاراگراف ListFormat.List به یک شیء مشترک List اشاره می‌کند | برای پاراگراف دوم فهرست خود را از طریق ListCollection.AddCopy(srcList) فراهم کنید، به‌جای استفاده مجدد از همان List |
| یک رشته قالب شماره‌گذاری سفارشی همان‌طور که انتظار می‌رود نمایش داده نمی‌شود | ListLevel.NumberFormat با الگوی مورد انتظار برای NumberStyle سطح مطابقت ندارد | تأیید کنید که NumberFormat و NumberStyle برای سطح در حال ویرایش به‌صورت سازگار تنظیم شده‌اند |
| فاصله‌گذاری لیست پس از تغییر سطوح به‌صورت برنامه‌نویسی اشتباه به نظر می‌رسد | ListLevelNumber به‌صورت مستقیم تنظیم شد بدون به‌روزرسانی ویژگی‌های موقعیت مرتبط | به‌جای تنظیم مستقیم ListLevelNumber، از ListFormat.ListIndent()/ListOutdent() استفاده کنید |
| یک گلوله تصویری نمایش داده نمی‌شود | گلوله تصویری برای سطح ایجاد نشده است، یا قالب‌بندی پیش‌فرض گلوله متنی هنوز فعال است | قبل از حذف قالب‌بندی گلوله متنی، ListLevel.CreatePictureBullet() را فراخوانی کنید و داده‌های تصویر را فراهم کنید |
FAQ
تفاوت List و ListFormat چیست؟
List تعریف قابل استفاده مجدد شماره‌گذاری/گلوله‌ای است که بین پاراگراف‌ها به‌اشتراک گذاشته می‌شود؛ ListFormat به ازای هر پاراگراف است — این نشان می‌دهد که یک پاراگراف خاص از کدام List استفاده می‌کند و در چه سطحی، از طریق ListFormat.List و ListLevelNumber.
چگونه بررسی کنم که آیا یک پاراگراف بخشی از فهرست است یا خیر؟
بر ListFormat.IsListItem مربوط به قالب‌بندی پاراگراف بخوانید؛ اگر true، ListFormat.List و ListLevelNumber توصیف می‌کنند که به کدام فهرست و سطح تعلق دارد.
چگونه یک فهرست جدید را طوری تنظیم کنم که شماره‌گذاری آن از ۱ شروع شود و مستقل از فهرست موجود باشد؟
از ListCollection.AddCopy(srcList) برای ایجاد یک نسخه مستقل از تعریف فهرست استفاده کنید، سپس آن نسخه را به پاراگراف‌های جدید اعمال کنید — به جای استفاده مجدد از List اصلی که شمارشگر یکسان را ادامه می‌دهد.
چگونه می‌توانم یک فهرست بولت‌دار یا شماره‌دار را از ابتدا ایجاد کنم؟
از ListFormat.ApplyBulletDefault() یا ApplyNumberDefault() برای قالب‌بندی پیش‌فرض ورد استفاده کنید، یا از ListCollection.Add(listTemplate) به همراه مقدار ListTemplate برای شروع از یکی از قالب‌های پیش‌تعریف‌شده ورد و سفارشی‌سازی List.ListLevels حاصل استفاده کنید.
چگونه می‌توانم قالب شماره را کنترل کنم، به‌عنوان مثال «1)» به‌جای «1.»؟
در سطح مربوطه، ListLevel.NumberFormat را به رشته قالب مورد نظر تنظیم کنید، به‌همراه NumberStyle برای سبک عددی خود.
API Reference خلاصه
| کلاس/متد | توضیح |
|---|---|
List | تعریف لیست قابل استفاده مجدد (شماره‌گذاری/نقطه) |
ListCollection | مجموعهٔ تمام فهرست‌ها در یک سند |
ListCollection.Add(listTemplate) / AddCopy(srcList) | یک فهرست را از یک قالب پیش‌تعریف‌شده ایجاد کنید، یا یک فهرست موجود را کپی کنید |
ListFormat | مرجع برای هر پاراگراف به یک List و سطح جاری |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | قالب‌بندی پیش‌فرض نقطه‌دار یا عددی را بر یک پاراگراف اعمال کنید |
ListLevel | قالب‌بندی شماره‌گذاری/گلوله برای یک سطح از List |
ListLevel.NumberStyle / NumberFormat | سبک عددی و رشته قالب برای یک سطح |
ListLabel | برچسب رندر شده (متن و مقدار) برای یک آیتم خاص از لیست |
ListTemplate | Enum از قالب‌های پیش‌تعریف‌شده لیست Word |
