String.prototype.includes()‎

الدالة String.prototype.includes()‎ تُحدِّد إن كانت تحتوي سلسلةٌ نصيةٌ على سلسلةٍ نصيةٍ أخرى، وتُعيد القيمة true أو false.

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

str.includes(searchString[, position])

searchString

السلسلة النصية التي سيُبحَث عنها ضمن السلسلة النصية الأصلية.

position

قيمة اختيارية، وهي الموضع ضمن السلسلة النصية التي نريد البدء منه في البحث عن السلسلة النصية searchString، القيمة الافتراضية هي 0.

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

القيمة true إذا عُثِرَ على السلسلة النصية searchString في أيّ مكان ضمن السلسلة النصية الأصلية، وإلا فستُعاد القيمة false.

الوصف

هذه الدالة تسمح لنا بمعرفة إن كانت تحتوي سلسلةٌ نصيةٌ ما على سلسلةٍ نصيةٍ أخرى.

حالة الأحرف

الدالة includes()‎ حساسةٌ لحالة الأحرف، أي أنَّ التعبير البرمجي الآتي سيُعيد القيمة false:

'Blue Whale'.includes('blue'); // false

أمثلة

المثال الآتي يستخدم الدالة includes()‎ للبحث عن سلاسل نصية فرعية:

var str = 'To be, or not to be, that is the question.';

console.log(str.includes('To be'));       // true
console.log(str.includes('question'));    // true
console.log(str.includes('nonexistent')); // false
console.log(str.includes('To be', 1));    // false
console.log(str.includes('TO BE'));       // false

تعويض نقص دعم المتصفحات

أُضيفَت هذه الدالة إلى معيار ECMAScript 2015، وقد لا تتوافر في جميع المتصفحات بعد، لكن يمكنك استخدام الشيفرة الآتية لتعريفها في المتصفحات التي لا تدعمها:

if (!String.prototype.includes) {
  String.prototype.includes = function(search, start) {
    'use strict';
    if (typeof start !== 'number') {
      start = 0;
    }
    
    if (start + search.length > this.length) {
      return false;
    } else {
      return this.indexOf(search, start) !== -1;
    }
  };
}

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

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

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

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

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