`String.prototype.replace()‎`

الدالة String.prototype.replace()‎ تُعيد سلسلةً نصيةً جديدةً فيها بعض أو جميع الأجزاء المُطابَقة عبر النمط pattern قد استبدلتها السلسلة النصية replacement. لاحظ أنَّ النمط pattern يمكن أن يكون سلسلةً نصيةً أو كائن RegExp، ويمكن أن يكون الوسيط replacement سلسلةً نصيةً أو دالةً التي ستُستدعى لكل مُطابَقة.

لاحظ أنَّ السلسلة النصية الأصلية ستبقى دون تعديل.

البنية العامة

str.replace(regexp|substr, newSubstr|function)

`regexp` (أي pattern)

كائن RegExp الذي ستبدّل الأجزاء المُطابَقة به إلى السلسلة النصية newSubStr أو بالقيمة المعادة من الدالة function.

`substr` (أي pattern)

سلسلة نصية String التي ستُبدَّل إلى newSubString، وستُستبدَل أوّل مطابقة لهذه السلسلة النصية فقط.

`newSubStr` (أي replacement)

السلسلة النصية التي ستوضع بدلًا من النمط regexp أو السلسلة النصية substr. وهنالك عددٌ من الأنماط المدعومة، والمذكورة في قسم «تحديد سلسلة نصية كوسيط» أدناه.

`function` (أي replacement)

الدالة التي ستُستدعى لإنشاء سلسلة نصية فرعية التي ستُستخدَم لاستبدال القيم المُطابَقة عبر regexp أو substr. الوسائط التي تقبلها هذه الدالة مشروحة في قسم «تحديد دالة كويسط» أدناه.

القيمة المعادة

سلسلةٌ نصيةٌ جديدةٌ جرى فيها استبدال بعض أو جميع الأجزاء المُطابَقة.

الوصف

هذه الدالة لن تُغيّر كائن String الذي استدعيت عليه، وإنما ستُعيد سلسلةً نصيةً جديدةً.

لإجراء بحث واستبدال عام (global، أي في كامل السلسلة النصية، ولن يتوقف عند أوّل مطابقة)، فضمِّن الراية g في التعبير النمطي.

تحديد سلسلة نصية كوسيط

يمكن أن يكون البديل (replacement) سلسلةً نصيةً تتضمن الأنماط الآتية:

النمط	سيُضيف
`$$`	سيُضيف محرف `$`.
`‎$&‎`	سيُضيف السلسلة النصية الفرعية التي جرت مطابقتها.
‎$`‎	سيُضيف القسم من السلسلة النصية الذي يسبق السلسلة النصية الفرعية التي جرت مطابقتها.
`‎$'‎`	سيُضيف القسم من السلسلة النصية الذي يلي السلسلة النصية الفرعية التي جرت مطابقتها.
`‎$n‎`	إضافة السلسلة النصية التي جربت مطابقتها بين قوسين (أي نمط فرعي) على فرض أنَّ الوسيط الأوّل هو تعبير نمطي `RegExp`. لاحظ أنَّ الترقيم يبدأ من 1، و `n` هو عدد صحيح موجب أقل من 100.

تحديد دالة كوسيط

يمكنك تحديد دالة كوسيطٍ ثان، وفي هذه الحالة، ستُستدعى الدالة بعد إجراء مطابقة، وستُستخدَم القيمة المُعادة من الدالة كبديل (replacement) عن السلسلة النصية المُطابَقة. لاحظ أنَّ هذه الدالة ستُستدعى عدِّة مرات حتى تنتهي عملية استبدال جميع السلاسل النصية المُطابَقة وذلك إذا كان أوّل وسيط هو نمط RegExp عام (أي له الراية g).

ملاحظة: الأنماط المذكورة في القسم السابق لا تنطبق على هذه الدوال.

تأخذ الدالة الوسائط الآتية:

الاسم المحتمل	القيمة المعطية
match	السلسلة النصية الفرعية التي جرت مطابقتها (وهي تماثل النمط `‎$&`‎ أعلاه).
`p1, p2, ...‎`	على فرض أنَّ أوّل وسيط مُمرَّر إلى الدالة `replace` هو تعبير نمطي `RegExp`، فهذه الوسائط ستُشير إلى أوّل نمط فرعي (بين قوسين). وهي تماثل ‎`$1` و `‎$2` ... في الجدول أعلاه. على سبيل المثال، إذا كان لدينا التعبير النمطي ‎`/(\a+)(\b+)/‎` فسيشير الوسيط `p1` إلى ‎`\a+`‎ و `p2` إلى ‎`\b+‎`.
`offset`	مقدار إزاحة السلسلة النصية الفرعية من بداية السلسلة النصية الأصلية. (على سبيل المثال، إذا كانت السلسلة النصية الأصلية كلها هي `'abcd'`، وكانت السلسلة النصية الفرعية التي جرت مطابقتها هي `'bc'`، فستكون قيمة هذا الوسيط هي `1`).
`string`	كامل السلسلة النصية التي جرت معالجتها.

لاحظ أنَّ عدد الوسائط سيعتمد على كون الوسيط الأوّل المُمرَّر إلى الدالة replace هو كائن RegExp، وإذا كان كذلك، فما هو عدد الأنماط الفرعية (التي بين قوسين) الموجودة فيه.

function replacer(match, p1, p2, p3, offset, string) {
  // p1 is nondigits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(' - ');
}
var newString = 'abc12345#$*%'.replace(/([^\d]*)(\d*)([^\w]*)/, replacer);
console.log(newString);  // abc - 12345 - #$*%

أمثلة

استخدام تعبير نمطي مع الدالة `replace()‎`

سنُعرِّف في المثال الآتي تعبيرًا نمطيًا RegExp مع الراية i التي تتجاهل حالة الأحرف:

var str = 'It was the night before BD...';
var newstr = str.replace(/bd/i, 'Birthday');
console.log(newstr);  // It was the night before Birthday...

إجراء الاستبدال على كامل السلسلة النصية مع تجاهل حالة الأحرف

يمكن إجراء عملية استبدال على كامل السلسلة (وليس أوّل مُطابقة فقط) عند استخدام التعابير النمطية، ففي المثال الآتي سيتضمن التعبير النمطي الرايتين g و i مما يسمح لنا باستبدال جميع حالات ورود الكلمة apples وتحويلها إلى oranges:

var re = /apples/gi;
var str = 'Apples are round, and apples are juicy.';
var newstr = str.replace(re, 'oranges');
console.log(newstr);  // oranges are round, and oranges are juicy.

التبديل بين الكلمات في سلسلة نصية

المثال الآتي سيبدِّل بين الكلمات، وسنستخدم الأنماط ‎$1 و ‎$2 لفعل ذلك:

var re = /(\w+)\s(\w+)/;
var str = 'John Smith';
var newstr = str.replace(re, '$2, $1');
console.log(newstr);  // Smith, John

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	نعم	نعم	نعم	نعم

مصادر ومواصفات

مسودة المعيار ECMAScript Latest Draft.
معيار ECMAScript 2015 (6th Edition)‎.
معيار ECMAScript 5.1.
معيار ECMAScript 3rd Edition .