JavaScript/Array/includes

الدالة Array.prototype.includes()‎ تُحدِّد إن كانت المصفوفة تحتوي على عنصر معيّن، وتُعيد true أو false.

var array1 = [1, 2, 3];

console.log(array1.includes(2)); // true

var pets = ['cat', 'dog', 'bat'];

console.log(pets.includes('cat')); // true

console.log(pets.includes('at')); // false

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

arr.includes(searchElement[, fromIndex])

searchElement

العنصر الذي نريد البحث عنه.

fromIndex

الفهرس الذي نريد البدء منه في البحث عن searchElement، والقيم السالبة ستؤدي إلى بدء البحث من الفهرس array.length + fromIndex تصاعديًا. القيمة الافتراضية هي 0.

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

قيمة منطقية (Boolean).

أمثلة

أمثلة بسيطة عن الدالة includes

[1, 2, 3].includes(2);     // true
[1, 2, 3].includes(4);     // false
[1, 2, 3].includes(3, 3);  // false
[1, 2, 3].includes(3, -1); // true
[1, 2, NaN].includes(NaN); // true

قيمة fromIndex أكبر أو تساوي عدد عناصر المصفوفة

إذا كانت قيمة الوسيط fromIndex أكبر أو تساوي عدد عناصر المصفوفة (length) فستُعاد القيمة false؛ ذلك لأنَّ المصفوفة غير قابلة للبحث.

var arr = ['a', 'b', 'c'];

arr.includes('c', 3);   // false
arr.includes('c', 100); // false

الفهرس المحسوب أقل من 0

إذا كانت قيمة الوسيط fromIndex سالبةً، فستُستخدَم القيمة المحسوبة (ناتج array.length + fromIndex) لبدء البحث عن القيمة searchElement؛ لكن إذا كان الفهرس المحسوب أقل من الصفر، فستتم عملية البحث في كامل المصفوفة.

// array length : 3
// fromIndex: -100
// computed index: 3 + (-100) = -97

var arr = ['a', 'b', 'c'];

arr.includes('a', -100); // true
arr.includes('b', -100); // true
arr.includes('c', -100); // true

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

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

// https://tc39.github.io/ecma262/#sec-array.prototype.includes
if (!Array.prototype.includes) {
  Object.defineProperty(Array.prototype, 'includes', {
    value: function(searchElement, fromIndex) {

      if (this == null) {
        throw new TypeError('"this" is null or not defined');
      }

      // 1. Let O be ? ToObject(this value).
      var o = Object(this);

      // 2. Let len be ? ToLength(? Get(O, "length")).
      var len = o.length >>> 0;

      // 3. If len is 0, return false.
      if (len === 0) {
        return false;
      }

      // 4. Let n be ? ToInteger(fromIndex).
      //    (If fromIndex is undefined, this step produces the value 0.)
      var n = fromIndex | 0;

      // 5. If n ≥ 0, then
      //  a. Let k be n.
      // 6. Else n < 0,
      //  a. Let k be len + n.
      //  b. If k < 0, let k be 0.
      var k = Math.max(n >= 0 ? n : len - Math.abs(n), 0);

      function sameValueZero(x, y) {
        return x === y || (typeof x === 'number' && typeof y === 'number' && isNaN(x) && isNaN(y));
      }

      // 7. Repeat, while k < len
      while (k < len) {
        // a. Let elementK be the result of ? Get(O, ! ToString(k)).
        // b. If SameValueZero(searchElement, elementK) is true, return true.
        if (sameValueZero(o[k], searchElement)) {
          return true;
        }
        // c. Increase k by 1. 
        k++;
      }

      // 8. Return false
      return false;
    }
  });
}

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	47	43	غير مدعومة	34	9

على النقيض من متصفح IE، يدعم Edge هذه الميزة بدءًا من الإصدار 14.

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

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