کار با فیلدهای ایندکس و جداول
کار با فیلدهای فهرست و جداول
این راهنما نشان می‌دهد چگونه با خانواده فیلدهای «Index and Tables» ورد کار کنید — فیلدهایی که پشت فهرست مطالب، فهرست، جدول اشکال و جدول منابع قرار دارند. هر یک از این‌ها زیرکلاس Field در فضای‌نام Aspose.Words.Fields هستند: FieldToc (فهرست مطالب یا اشکال)، FieldIndex (فهرست)، FieldXE (ورودی فهرست)، FieldToa (جدول منابع)، FieldTA (ورودی جدول منابع یا استناد)، FieldTC (ورودی فهرست مطالب)، و FieldRD (سند مرجع، برای ساخت فهرست یا فهرست ترکیبی در چندین فایل).
کلاس پایه فیلد
هر کلاس فیلد در این خانواده از Field ارث می‌برد، که Start، Separator و End را در دسترس می‌گذارد (گره‌های FieldStart، FieldSeparator و FieldEnd که فیلد را در جریان اجرا محدود می‌کردند)، Type (یک مقدار FieldType — FieldTOC، FieldIndex، FieldTOA، FieldTOCEntry، FieldIndexEntry، FieldTOAEntry یا FieldRefDoc برای این خانواده)، Result/DisplayResult (متن محاسبه‌شده فعلی فیلد)، IsLocked و IsDirty، و متدهای GetFieldCode()، Update()، Unlink() و Remove(). Update() نتیجه فیلد را دوباره محاسبه می‌کند؛ برای یک فهرست مطالب، به این معناست که لیست ورودی‌ها را از سرعنوان‌های سند یا علامت‌های FieldTC بازسازی می‌کند.
درج فهرست مطالب
DocumentBuilder.InsertTableOfContents(switches) یک FieldToc را در موقعیت فعلی سازنده درج می‌کند، با استفاده از یک رشته سوئیچ فیلد ورد (به عنوان مثال "\o \"1-3\" \h \z \u") برای کنترل اینکه کدام سطوح سرعنوان شامل شوند و نتیجه چگونه قالب‌بندی شود — همان سوئیچ‌هایی که ورد هنگام وارد کردن فهرست مطالب از طریق رابط کاربری می‌نویسد. پس از درج، FieldToc.UpdatePageNumbers() بخش شماره صفحه ورودی‌های موجود را دوباره محاسبه می‌کند. FieldToc همچنین ویژگی‌هایی را که ساختار فهرست مطالب را مستقیماً کنترل می‌کنند، در دسترس می‌گذارد: HeadingLevelRange و EntryLevelRange (کدام سطوح طرح‌ریزی شامل می‌شوند)، EntryIdentifier (شناسه فیلد TC که فهرست مطالب باید جمع‌آوری کند، برای ساخت چندین فهرست مطالب از علامت‌های مختلف FieldTC)، InsertHyperlinks، PreserveTabs/PreserveLineBreaks، EntrySeparator/SequenceSeparator، BookmarkName، و — برای جدول اشکال به جای فهرست مطالب — TableOfFiguresLabel و CaptionlessTableOfFiguresLabel.
نشانه‌گذاری ورودی‌های سفارشی فهرست مطالب
همه ورودی‌های فهرست مطالب از سبک عنوان نمی‌آیند. FieldTC یک مکان خاص را به‌عنوان ورودی فهرست مطالب مستقل از سبک پاراگراف علامت‌گذاری می‌کند: FieldTC.Text متن ورودی است، EntryLevel سطح طرح‌بندی‌ای است که باید در آن ظاهر شود، TypeIdentifier آن را به یک FieldToc.EntryIdentifier هنگام ساخت بیش از یک فهرست مطالب وصل می‌کند، و OmitPageNumber شماره صفحه برای آن ورودی را حذف می‌کند.
ساخت فهرست
FieldIndex فیلد INDEX را پیاده‌سازی می‌کند که نشانگرهای FieldXE (ورودی فهرست) یک سند را به یک فهرست حروف الفبا تبدیل می‌سازد. FieldXE.Text متن ورودی است، EntryType ورودی‌ها را با استفاده از سینتکس جدا شده با دو نقطه به سطوح زیرمجموعه گروه‌بندی می‌کند، PageRangeBookmarkName یک نشانک را علامت‌گذاری می‌کند که دامنه آن به جای یک شماره صفحهٔ واحد، یک بازهٔ صفحه‌ای در فهرست می‌شود، و IsBold/IsItalic مرجع صفحهٔ حاصل را قالب‌بندی می‌کنند. در سمت FieldIndex، Heading جداسازهای حروف سرصفحه (A, B, C…) را وارد می‌کند، LetterRange فهرست را به زیرمجموعه‌ای از حروف الفبا محدود می‌کند، RunSubentriesOnSameLine چیدمان زیرورودی‌ها را کنترل می‌کند، و PageNumberSeparator/PageRangeSeparator/SequenceSeparator/CrossReferenceSeparator نقطه‌گذاری بین یک ورودی و مرجع صفحهٔ آن را تنظیم می‌نمایند. FieldIndexFormat به طور جداگانه سبک‌های بصری فهرست داخلی Word را فهرست می‌کند (Template, Classic, Fancy, Modern, Bulleted, Formal, Simple).
فهرست مراجع
FieldToa و FieldTA معادل مراجع FieldIndex/FieldXE هستند: FieldTA یک ارجاع در متن را علامت‌گذاری می‌کند (LongCitation و متن ShortCitation، EntryCategory برای گروه‌بندی آن تحت عنوانی مانند “Cases” یا “Statutes”، و IsBold/IsItalic برای قالب‌بندی)، و FieldToa این ارجاعات را در یک جدول جمع‌آوری می‌کند، به‌طوری که EntryCategory دستهٔ مورد نظر برای جمع‌آوری را انتخاب می‌کند، UseHeading و UsePassim سرعنوان‌های دسته و قرارداد “passim” برای منابعی که بارها ارجاع شده‌اند را کنترل می‌کنند، و PageRangeSeparator/PageNumberListSeparator/SequenceSeparator/EntrySeparator/RemoveEntryFormatting چیدمان را تنظیم می‌کنند.
ارجاع به محتوا از اسناد دیگر
FieldRD فیلد RD را پیاده‌سازی می‌کند، که به فیلد فهرست مطالب (TOC)، فهرست یا جدول مراجع می‌گوید هنگام کامپایل، ورودی‌ها را از فایل دیگری شامل کند — FieldRD.FileName سند مرجع است، و IsPathRelative تعیین می‌کند آیا آن مسیر نسبت به سند جاری حل شود یا نه.
نکات و بهترین روش‌ها
- رشتهٔ سوئیچ فهرست مطالب (TOC) را همان‌طور که ورد می‌سازد (
\o "1-3" \h \z \u) بسازید به‌جای اینکه هر ویژگیFieldTocرا به‌صورت جداگانه پیکربندی کنید، سپس فقط ویژگی‌های خاصی را که نیاز به تغییر دارند، بعداً تنظیم کنید. - پس از تغییر محتوا،
FieldToc.UpdatePageNumbers()(یاField.Update()) را فراخوانی کنید تا فهرست مطالب، فهرست نمایه یا جدول مراجع، سند جاری را نشان دهد نه نتایج منسوخ شده‌ای که هنگام درج آن وجود داشته‌اند. - از
FieldTC.TypeIdentifierبه همراهFieldToc.EntryIdentifierاستفاده کنید وقتی سند به بیش از یک فهرست مطالب نیاز دارد (مثلاً یک فهرست مطالب اصلی و یک جدول شکل‌ها جداگانه) که از مجموعه‌های ورودی متفاوت ساخته شده‌اند. - به‌جای فرمت‌گذاری دستی بازهٔ صفحه در متن ورودی،
FieldXE.PageRangeBookmarkName(یا علامت‌گذاری بازهٔ معادلFieldTA) را تنظیم کنید تا فهرست/نمایه در صورت جابه‌جایی محتوا ثابت بماند. - به یاد داشته باشید که شماره‌های صفحه در نتایج INDEX/TOC/TOA این نسخه به مقادیر جای‌دار تبدیل می‌شوند نه شماره‌های واقعی صفحه، زیرا چیدمان صفحه و صفحه‌بندی جزئی از این نسخه نیستند.
مسائل رایج
| مسئله | دلیل | راه‌حل |
|---|---|---|
| فهرست مطالب سرفصل‌های مورد انتظار را شامل نمی‌شود | رشته سوئیچ فهرست مطالب (یا HeadingLevelRange) سطوح طرح‌واره را حذف می‌کند | سوئیچ‌های پاس داده شده به InsertTableOfContents را تنظیم کنید یا FieldToc.HeadingLevelRange را مقداردهی کنید |
| یک ورودی فهرست در مکان مورد انتظار ظاهر نمی‌شود | علامت FieldXE مربوطه موجود نیست، یا نحو زیرسطح EntryType آن با آنچه FieldIndex انتظار دارد مطابقت ندارد | تأیید کنید که علامت‌های FieldXE وجود دارند و مقادیر EntryType آن‌ها به‌صورت یکسان قالب‌بندی شده‌اند |
| نتایج فیلد پس از ویرایش محتوا قدیمی به‌نظر می‌رسند | فیلد پس از ویرایش به‌روزرسانی نشد | متد Update() را روی فیلد فراخوانی کنید (یا UpdateFields() را روی Document اجرا کنید) |
| ورودی‌های یک سند دیگر هنگام کامپایل گنجانده نمی‌شوند | هیچ FieldRDی که به آن سند ارجاع می‌دهد وجود ندارد، یا IsPathRelative با نحوه‌ی حل مسیر مطابقت ندارد | یک FieldRD اضافه کنید با تنظیمات صحیح FileName و IsPathRelative |
FAQ
چگونه می‌توانم فهرست مطالب را به‌صورت برنامه‌نویسی درج کنم؟
متد DocumentBuilder.InsertTableOfContents(switches) را با رشته سوئیچ به سبک Word، مانند "\o \"1-3\" \h \z \u"، در موقعیتی که فهرست مطالب (TOC) باید ظاهر شود، فراخوانی کنید.
چگونه متن را به عنوان یک ورودی فهرست (index) علامت‌گذاری کنم؟
یک فیلد FieldXE را در آن مکان قرار دهید (مثلاً از طریق DocumentBuilder.InsertField) و ویژگی Text آن را روی متن ورودی تنظیم کنید؛ FieldIndex تمام علامت‌های FieldXE را در سند به نتیجه فهرست ترکیب می‌کند.
تفاوت بین FieldTC و ورودی‌های فهرست مبتنی بر عنوان چیست؟
رفتار پیش‌فرض فهرست مطالب در Word ورودی‌ها را از پاراگراف‌ها با استفاده از سبک‌های عنوان جمع‌آوری می‌کند. FieldTC به شما اجازه می‌دهد یک مکان دلخواه را به عنوان ورودی فهرست (TOC) علامت‌گذاری کنید، مستقل از سبک پاراگراف، که FieldToc می‌تواند آن را از طریق مقادیر مطابقت‌دهنده EntryIdentifier/TypeIdentifier شامل شود.
چگونه پس از تغییرات سند، فهرست مطالب یا فهرست (index) را به‌روز کنم؟
متد Update() را بر روی فیلد خاص فراخوانی کنید (مثلاً FieldToc.Update()، یا FieldToc.UpdatePageNumbers() فقط برای شماره صفحات)، یا Document.UpdateFields() را برای به‌روزرسانی همه فیلدهای سند اجرا کنید.
آیا می‌توانم یک فهرست مطالب یا فهرست (index) را در چندین سند ترکیب کنم؟
بله — یک فیلد FieldRD وارد کنید که به هر سند اضافه‌ای از طریق FileName اشاره کند؛ فیلد ترکیبی (FieldToc، FieldIndex یا FieldToa) هنگام به‌روزرسانی، ورودی‌های سندهای ارجاع‌شده را شامل می‌شود.
API Reference خلاصه
| کلاس/متد | توضیح |
|---|---|
Field | کلاس پایه برای تمام انواع فیلد، از جمله Start/Separator/End، Type، Update() |
DocumentBuilder.InsertTableOfContents(switches) | یک FieldToc را با استفاده از سوئیچ‌های TOC به سبک Word وارد کنید |
FieldToc | فیلد TOC را پیاده‌سازی می‌کند (فهرست مطالب یا فهرست شکل‌ها) |
FieldTC | یک ورودی سفارشی فهرست مطالب را در مکان مشخصی علامت‌گذاری می‌کند |
FieldIndex | فیلد INDEX را پیاده‌سازی می‌کند و نشانه‌های FieldXE را جمع‌آوری می‌نماید |
FieldXE | یک مکان را به‌عنوان ورودی فهرست علامت‌گذاری می‌کند |
FieldToa | فیلد جدول مراجع را پیاده‌سازی می‌کند و نشانگرهای FieldTA را ترکیب می‌نماید |
FieldTA | یک استناد را برای جدول مراجع علامت‌گذاری می‌کند |
FieldRD | محتویات سند دیگری را هنگام ترکیب فهرست مطالب (TOC)، فهرست یا جدول مراجع ارجاع می‌دهد |
FieldIndexFormat | شمارشگر سبک‌های بصری فهرست داخلی ورد |
