جستجو و جایگزینی
جستجو و جایگزینی
Aspose.Words FOSS برای .NET امکان جستجو و جایگزینی مبتنی بر عبارات منظم را از طریق Range.Replace() فراهم می‌کند، که می‌توان آن را از طریق FindReplaceOptions پیکربندی کرد و برای سناریوهای پیشرفته، یک پیاده‌سازی سفارشی IReplacingCallback از فضای‌نام Aspose.Words.Replacing ارائه می‌دهد.
جستجو و جایگزینی پایه‌ای
Range.Replace(pattern, replacement) یک جستجو و جایگزینی مبتنی بر عبارات منظم را در سراسر بازه اجرا می‌کند — تمام سند، هنگامی که بر روی Document.Range فراخوانی شود. نسخهٔ overload Replace(pattern, replacement, options) یک شیء FindReplaceOptions را برای کنترل دقیق‌تر می‌پذیرد: MatchCase و FindWholeWordsOnly رفتار تطبیق را تنظیم می‌کنند، Direction (یک مقدار FindReplaceDirection، Forward یا Backward) جهت جستجو را کنترل می‌کند، و ApplyFont / ApplyParagraphFormat اجازه می‌دهند یک جایگزینی قالب‌بندی جدیدی به‌جای تنها متن جدید حمل کند.
گزینه‌های آگاه از قالب‌بندی و ساختاری
FindReplaceOptions چندین پرچم شامل می‌شود که تعیین می‌کند کدام ساختارهای سند می‌توانند در تطبیق عبور یا نادیده گرفته شوند: IgnoreDeleted و IgnoreInserted کنترل می‌کنند که آیا محتوای تغییرات ردیابی‌شده در تطبیق شرکت می‌کند یا نه، IgnoreFields و IgnoreFieldCodes کنترل می‌کنند که آیا متن نتیجهٔ فیلد و کدهای فیلد جستجو شوند، IgnoreFootnotes محتوای پاورقی/پایان‌نوشت را حذف می‌کند، و IgnoreStructuredDocumentTags و IgnoreShapes به ترتیب کنترل‌های محتوا و متن شکل‌ها را حذف می‌کنند. UseSubstitutions نحو جایگزینی عبارات منظم (مانند $1) را در رشتهٔ جایگزینی فعال می‌کند. LegacyMode و UseLegacyOrder رفتار تطبیق قدیمی‌تر را برای سازگاری با اسنادی که توسط منطق قبلی پردازش شده‌اند، حفظ می‌کنند.
منطق سفارشی جایگزینی با IReplacingCallback
برای منطق جایگزینی که نمی‌تواند به صورت یک رشته جایگزینی ثابت بیان شود، IReplacingCallback را پیاده‌سازی کنید و متد تک‌تایی Replacing(args) آن را، سپس پیاده‌سازی را به FindReplaceOptions.ReplacingCallback اختصاص دهید (یا مستقیماً به سازنده FindReplaceOptions(replacingCallback) پاس دهید). فراخوانی‌گر برای هر تطابق، یک شیء ReplacingArgs دریافت می‌کند که Match (تطابق عبارات منظم زیرین)، MatchNode / MatchEndNode (گره‌های سند حاوی تطابق)، MatchOffset، و یک رشته قابل تنظیم Replacement را افشا می‌کند. برگرداندن یک مقدار ReplaceAction از فراخوانی‌گر — Replace، Skip یا Stop — تعیین می‌کند که آیا آن تطابق خاص جایگزین شود، دست نخورده بماند یا کل عملیات جستجو/جایگزینی متوقف شود.
نکات و بهترین شیوه‌ها
- متد
Replace()را بر رویDocument.Rangeبرای جایگزینی در سرتاسر سند فراخوانی کنید، یا بر روی یکRangeمحدودتر (مانند بازه یک بخش منفرد) برای محدود کردن دامنه عملیات. - برای جلوگیری از مطابقت یک واژه جستجو به عنوان زیررشته‌ای از یک واژه بلندتر،
FindWholeWordsOnly = trueرا تنظیم کنید. - زمانی که می‌خواهید جایگزینی بر روی نتایج نمایش داده شدهٔ فیلد اعمال شود، نه بر روی متن دستورالعمل فیلد زیرین، از
IgnoreFieldCodes = trueاستفاده کنید. - وقتی متن جایگزین به زمینهٔ تطابق (گرهٔ اطراف، قالب‌بندی یا موقعیت) وابسته است و نه یک رشته ثابت، به جای پردازش پس از‌دست،
IReplacingCallbackرا ترجیح دهید. - برای پایان زودهنگام عملیات جستجو/جایگزینی پس از برآورده شدن یک شرط، به جای پردازش همهٔ تطابق‌های باقی‌مانده،
ReplaceAction.Stopرا از فراخوانی‌گر برگردانید.
مشکلات رایج
| مشکل | دلیل | رفع |
|---|---|---|
| جایگزینی قالب‌بندی جدید را اعمال نمی‌کند | ApplyFont/ApplyParagraphFormat در FindReplaceOptions تنظیم نشده است | ویژگی‌های قالب‌بندی مربوطه را بر روی شی options تنظیم کنید |
| مطابقت‌ها به‌صورت غیرمنتظره در حذف‌های تغییر پیگیری‌شده یافت شدند | IgnoreDeleted در مقدار پیش‌فرض خود باقی مانده است | مقدار IgnoreDeleted = true را تنظیم کنید تا محتوای بازبینی حذف شده را نادیده بگیرید. |
| ارجاع‌های گروه Regex در متن جایگزین جایگزین نمی‌شوند | UseSubstitutions فعال نیست | UseSubstitutions = true را تنظیم کنید تا جایگزینی به‌صورت $1 فعال شود |
| جایگزینی مبتنی بر کال‌بک در زمان مورد انتظار متوقف نمی‌شود | کال‌بک Replace/Skip را به‌جای Stop برمی‌گرداند | زمانی که عملیات باید پایان یابد، ReplaceAction.Stop را از Replacing() برگردانید |
FAQ
آیا Range.Replace() از عبارات منظم پشتیبانی می‌کند؟
بله — آرگومان pattern یک عبارت منظم است که در متن بازه مطابقت داده می‌شود.
چگونه متن را فقط در یک بخش خاص جایگزین کنم، نه در کل سند؟
متد Replace() را بر روی Range آن بخش فراخوانی کنید به جای Document.Range.
چگونه متن جایگزین را وابسته به آنچه مطابقت داده شد بسازم؟
متد IReplacingCallback را پیاده‌سازی کنید، جزئیات تطبیق را از ReplacingArgs بخوانید، ReplacingArgs.Replacement را به متن محاسبه‌شده تنظیم کنید و ReplaceAction.Replace را برگردانید.
آیا می‌توان جستجوی یافتن/جایگزینی را به صورت معکوس در سند انجام داد؟
بله — FindReplaceOptions.Direction را به FindReplaceDirection.Backward تنظیم کنید.
API Reference خلاصه
| کلاس / متد | توضیح |
|---|---|
Range.Replace() | جستجو/جایگزینی با عبارات منظم در یک بازه، با FindReplaceOptions اختیاری |
FindReplaceOptions | رفتار مطابقت، قالب‌بندی و دامنه ساختاری برای عملیات جایگزینی را پیکربندی می‌کند. |
FindReplaceDirection | Enum: Forward, Backward |
IReplacingCallback | رابط برای منطق جایگزینی سفارشی به ازای هر تطبیق |
ReplacingArgs | داده‌های مربوط به هر تطبیق که به IReplacingCallback.Replacing() ارسال می‌شود |
ReplaceAction | Enum کنترل‌کننده نتیجه هر تطبیق: Replace, Skip, Stop |
