چگونه با پیوندها و مراجع Word در .NET کار کنیم
این راهنما نشان می‌دهد چگونه پیوندهای ابرمتنی، ارجاعات متقابل به نشانک‌ها، فیلدهای مقدار درخواست شده و فیلدهای استنادی را در Aspose.Words FOSS برای .NET, با استفاده از FieldHyperlink, FieldRef, FieldPageRef, FieldCitation, و سایر پیوندها و ارجاعات Field زیرکلاس‌ها در فضای‌نام Aspose.Words.Fields . این راهنما شامل افزودن یک پیوند ساده، ایجاد نشانک‌ها و ارجاع متقابل به آنها، درخواست مقادیر هنگام به‌روزرسانی فیلد، و استناد به منابع کتابشناسی است.
راهنمای گام به گام
مرحله 1: نصب بسته
Aspose.Words FOSS for .NET هنوز بستهٔ NuGet را منتشر نکرده است – به‌جای آن کتابخانه را از منبع بسازید. https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git را کلون کنید، سپس Aspose.Words.sln را در پیکربندی Release با SDK .NET بسازید و اسمبلی Aspose.Words حاصل را از پروژهٔ خود ارجاع دهید. این کتابخانه هدف .NET Standard 2.0 را دارد، بنابراین بر روی .NET Framework 4.6.2+ و .NET 6/8/10 اجرا می‌شود.
مرحله 2: وارد کردن کلاس‌های مورد نیاز
یک دستور using Aspose.Words; برای Document و DocumentBuilder اضافه کنید، و یک دستور using Aspose.Words.Fields; برای FieldHyperlink، FieldRef، FieldPageRef، FieldNoteRef، FieldStyleRef، FieldSet، FieldAsk، FieldFillIn، FieldCitation، FieldBibliography و سایر کلاس‌های فیلد که این راهنما پوشش می‌دهد، اضافه کنید.
مرحله ۳: درج یک هایپرلینک
برای یک هایپرلینک ساده، DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark) را فراخوانی کنید – isBookmark: false را برای مقصد URL یا true برای پیوند به یک نشانک در همان سند پاس کنید. زمانی که نیاز به ویژگی‌هایی است که میانبر آنها را نشان نمی‌دهد، به‌صورت مستقیم یک FieldHyperlink بسازید: Address و SubAddress URL هدف یا مکان داخل سند را نگه می‌دارند، ScreenTip ابزار راهنمایی (tooltip) را تنظیم می‌کند، OpenInNewWindow و IsImageMap پرچم‌های نمایش هستند، و Target یک چارچوب مرورگر را نام‌گذاری می‌کند.
مرحله ۴: ایجاد یک نشانک برای ارجاع
DocumentBuilder.StartBookmark(bookmarkName) را قبل از محتوایی که نشانک باید پوشش دهد فراخوانی کنید، و DocumentBuilder.EndBookmark(bookmarkName) را پس از آن، به‌طوری که برای هر دو فراخوانی از همان نام استفاده کنید. DocumentBuilder.MoveToBookmark(bookmarkName) مکان‌نمای (cursor) را به یک نشانک که از قبل وجود دارد می‌برد – که برای حرکت به موقعیتی پیش از درج یک فیلد ارجاع متقابل در نزدیکی آن مفید است.
مرحله ۵: درج یک ارجاع متقابل به آن نشانک
FieldRef (فیلد REF)، FieldPageRef (PAGEREF) و FieldNoteRef (NOTEREF) هر کدام محتوا را از یک نشانک نام‌گذاری شده از طریق ویژگی BookmarkName خود بازیابی می‌کنند. InsertHyperlink را تنظیم کنید تا ارجاع قابل کلیک شود، و InsertRelativePosition را برای گزارش موقعیت نسبی («بالا» / «پایین») به جای متن ارجاع‌شده تنظیم کنید. FieldRef همچنین گزینه‌های شماره‌گذاری پاراگراف را پشتیبانی می‌کند — InsertParagraphNumber، InsertParagraphNumberInFullContext، InsertParagraphNumberInRelativeContext، NumberSeparator — و IncludeNoteOrComment. FieldStyleRef (STYLEREF) به نزدیک‌ترین پاراگرافی که با StyleName مشخص شده قالب‌بندی شده است (به‌جای یک نشانک) مراجعه می‌کند، با SearchFromBottom برای جستجوی عقب‌گرد از موقعیت فیلد. FieldSet (SET) یک مقدار متنی نشانک‌گذاری‌شده را تعریف می‌کند — BookmarkName و BookmarkText — که یک فیلد REF در جای دیگر می‌تواند آن را بازیابی کند.
مرحله ۶: درخواست مقدار هنگام به‌روزرسانی
FieldAsk (ASK) و FieldFillIn (FILLIN) درخواست مقداری از هر کسی که فیلد را به‌روزرسانی می‌کند: set PromptText به متنی که به کاربر نمایش داده می‌شود، DefaultResponse برای مقدار پیش‌فرض، و PromptOnceOnMailMerge برای محدود کردن درخواست‌های مکرر در طول ادغام ایمیل. FieldAsk علاوه بر این، پاسخ خود را در BookmarkName تا فیلدهای دیگر بتوانند به آن ارجاع دهند. برای به‌روزرسانی‌های خودکار فیلدها، پاسخ‌ها را به‌صورت برنامه‌نویسی فراهم کنید نه اینکه به‌صورت تعاملی درخواست کنید؛ راهنمای راهنمای فیلدها برای رابط فراخوانی (callback) که این کار را انجام می‌دهد.
مرحله ۷: ارجاع به محتوای خارجی یا پیوند شده
FieldDde (DDE) و FieldDdeAuto (DDEAUTO) به محتوا در برنامه‌ای دیگر از طریق ProgId، SourceFullName و SourceItem پیوند می‌دهند، به‌طوری که InsertAsText، InsertAsHtml، InsertAsPicture، InsertAsRtf، InsertAsUnicode و InsertAsBitmap نمای درج‌شده را انتخاب می‌کنند، و AutoUpdate / IsLinked رفتار تازه‌سازی را کنترل می‌کنند. FieldLink (LINK) معادل OLE-link است و FormatUpdateType را اضافه می‌کند. FieldImport (IMPORT) و FieldIncludePicture (INCLUDEPICTURE) گرافیک خارجی را از طریق SourceFullName و GraphicFilter می‌کشند. FieldInclude (INCLUDE) و FieldIncludeText (INCLUDETEXT) محتوای سند خارجی را می‌کشند، به‌همراه BookmarkName برای محدودهٔ شامل‌شده و LockFields برای جلوگیری از تازه‌سازی آن؛ FieldIncludeText همچنین منابع XML را از طریق Encoding، MimeType، NamespaceMappings، XPath و XslTransformation پشتیبانی می‌کند.
مرحله ۸: ارجاع به بلوک‌های ساختمانی و ورودی‌های واژه‌نامه
FieldAutoText (AUTOTEXT)، FieldAutoTextList (AUTOTEXTLIST) و FieldGlossary (GLOSSARY) همگی از طریق EntryName به یک ورودی بلوک‌ساز نام‌گذاری‌شده ارجاع می‌دهند؛ FieldAutoTextList برای ارائه به شکل فهرست، ListStyle و ScreenTip را اضافه می‌کند.
مرحله ۹: درج فیلدهای استناد و کتابشناسی
FieldCitation (CITATION) و FieldBibliography (BIBLIOGRAPHY) محتوا را که از داده‌های کتاب‌نامه سند استخراج شده‌اند، رندر کنید. تنظیم FieldCitation.SourceTag (یا جایگزین AnotherSourceTag) برای شناسایی اینکه کدام منبع Prefix, Suffix, PageNumber, VolumeNumber, و Suppress* پرچم‌ها (SuppressAuthor, SuppressTitle, SuppressYear) برای کنترل نحوه قالب‌بندی استناد. FieldBibliography.SourceTag, FilterLanguageId, و FormatLanguageId کنترل می‌کند که کدام منابع در کتاب‌نامه رندر شده ظاهر شوند و به چه زبانی. این فیلدها فقط زمانی به‌درستی رندر می‌شوند که تطبیق Source رکوردها موجود باشند – ببینید راهنمای کتاب‌نامه برای ساختن آنها.
مشکلات رایج و راه‌حل‌ها
فیلد REF، PAGEREF یا NOTEREF نتیجه خطایی نشان می‌دهد این BookmarkName هدف آن در سند وجود ندارد. نشانک را با DocumentBuilder.StartBookmark() / EndBookmark() قبل از به‌روزرسانی فیلد.
فیلدهای ASK یا FILLIN به‌روزرسانی خودکار را مسدود می‌کنند هیچ callbackی برای تأمین پاسخ به‌صورت برنامه‌نویسی اختصاص داده نشده است. callback به‌روزرسانی فیلد توصیف‌شده در راهنمای فیلدها, یا تنظیم کنید DefaultResponse روی فیلد تا مقدار پیش‌فرض داشته باشد.
فیلد CITATION یا BIBLIOGRAPHY خالی رندر می‌شود این SourceTag با هیچ‌کدام مطابقت ندارد Source در داده‌های bibliography سند. مطابقت‌دار را اضافه کنید Source – ببینید راهنمای کتابشناسی.
فیلد DDE، DDEAUTO یا LINK تازه نمی‌شود این فیلدها به منبع خارجی OLE ارجاع می‌دهند که خارج از زمینه اصلی Windows/OLE در دسترس نیست. نتیجه ذخیره‌شده فیلد را به‌عنوان آخرین مقدار شناخته‌شده در آن وضعیت در نظر بگیرید.
یک پیوند درج‌شده با InsertHyperlink فاقد ویژگی‌ای است که من نیاز دارم DocumentBuilder.InsertHyperlink() یک میانبر است که هر … را نمایش نمی‌دهد FieldHyperlink ویژگی. ساخت یا بازیابی FieldHyperlink به‌صورت مستقیم برای تنظیم ویژگی‌هایی مانند ScreenTip or IsImageMap.
سوالات متداول
تفاوت FieldRef و FieldStyleRef چیست؟
FieldRef به محتوایی در یک نشانک نام‌گذاری‌شده (BookmarkName) ارجاع می‌دهد؛ در حالی که FieldStyleRef به نزدیک‌ترین پاراگرافی که با StyleName مشخص شده قالب‌بندی شده است، بدون وابستگی به نشانک‌ها، ارجاع می‌دهد.
چگونه یک لینک ساده را بدون ساختن یک Field به صورت دستی وارد کنم؟
فراخوانی DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark).
آیا این کلاس‌های فیلد لینک و ارجاع در یک فضای نام جداگانه نسبت به سایر فیلدها هستند؟
خیر – FieldHyperlink، FieldRef، FieldCitation و بقیه کلاس‌های بیان‌شده در اینجا زیرکلاس‌های معمولی Field در فضای نام Aspose.Words.Fields هستند، همان فضای نامی که برای تمام انواع دیگر فیلدها استفاده می‌شود.
فیلدهای استنادی چگونه با مدل داده‌های کتاب‌نامه مرتبط هستند؟
FieldCitation and FieldBibliography محتوا را با جستجو رندر کنید SourceTag در مقابل Source سوابق توصیف شده در راهنمای کتابشناسی – این کلاس‌های فیلد رندرینگ را مدیریت می‌کنند، در حالی که Source and Contributor کلاس‌ها داده‌های زیرین را نگهداری می‌کنند.
چگونه یک بوکمارک ایجاد کنم پیش از ارجاع به آن؟
قبل از محتوا DocumentBuilder.StartBookmark(bookmarkName) را فراخوانی کنید و پس از آن DocumentBuilder.EndBookmark(bookmarkName) را، به‌طوری که برای هر دو فراخوانی از یک نام استفاده شود.
