بحث واستبدال
بحث واستبدال
Aspose.Words FOSS لـ .NET يوفر بحثًا واستبدالًا قائمًا على التعبيرات النمطية عبر Range.Replace()، قابلًا للتكوين عبر FindReplaceOptions، وللحالات المتقدمة، تنفيذ مخصص لـ IReplacingCallback من مساحة الأسماء Aspose.Words.Replacing.
بحث واستبدال أساسي
Range.Replace(pattern, replacement) يقوم بتنفيذ بحث واستبدال قائم على التعبيرات النمطية عبر النطاق — المستند بالكامل، عند استدعائه على Document.Range. التحميل الزائد 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 |
