RegExp.prototype.[@@replace]()‎

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

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

regexp[Symbol.replace](str, newSubStr|function)

str

السلسلة النصية التي سنبحث عن مُطابَقة للتعبير النمطي فيها لاستبداله.

newSubStr

السلسلة النصية String التي ستستبدل السلسلة الفرعية، وهنالك عددٌ من الأنماط الفرعية المدعومة فيها، انظر قسم «تحديد سلسلة نصية كوسيط» في صفحة الدالة String.prototype.replace()‎ للتفاصيل.

function

الدالة التي ستُستدعى عند إنشاء السلسلة النصية الفرعية الجديدة، والوسائط التي تقبلها هذه الدالة مشروحة في قسم «تحديد دالة كوسيط» في صفحة الدالة String.prototype.replace()‎ للتفاصيل.

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

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

الوصف

تُستدعى هذه الدالة داخليًا في الدالة String.prototype.replace()‎ وذلك إذا كان الوسيط pattern هو كائن RegExp. فمثلًا، كلا المثالين الآتيين يُعيد النتيجة نفسها:

'abc'.replace(/a/, 'A');

/a/[Symbol.replace]('abc', 'A');

الغرض من وجود هذه الدالة هو السماح بإمكانية تخصيصها في الأصناف الفرعية المشتقة من RegExp.

إذا لم يكن الوسيط pattern هو كائن من النوع RegExp، فلن تستدعي الدالة String.prototype.replace()‎ هذه الدالة، ولن تُنِشئ كائن RegExp من الأساس.

أمثلة

استدعاء مباشر

ستُستخدَم هذه الدالة بنفس طريقة استخدام الدالة String.prototype.replace()‎:

var re = /-/g; 
var str = '2016-01-01';
var newstr = re[Symbol.replace](str, '.');
console.log(newstr);  // 2016.01.01

استخدام ‎@@replace في الأصناف الفرعية

يمكن للأصناف الفرعية المشتقة من الصنف RegExp إعادة تعريف الدالة ‎[@@replace]()‎ لتغيير سلوكها الافتراضي:

class MyRegExp extends RegExp {
  constructor(pattern, flags, count) {
    super(pattern, flags);
    this.count = count;
  }
  [Symbol.replace](str, replacement) {
    // Perform @@replace |count| times.
    var result = str;
    for (var i = 0; i < this.count; i++) {
      result = RegExp.prototype[Symbol.replace].call(this, result, replacement);
    }
    return result;
  }
}

var re = new MyRegExp('\\d', '', 3);
var str = '01234567';
var newstr = str.replace(re, '#'); // String.prototype.replace calls re[@@replace].
console.log(newstr); // ###34567

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

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

على النقيض من متصفح IE، يدعم Edge هذه الميزة.

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

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