Array.prototype.filter()‎

الدالة Array.prototype.filter()‎ تُنشِئ مصفوفةً جديدةً فيها جميع العناصر التي حققت دالة الاختبار المُمرَّرة إلى هذه الدالة.

var words = ['spray', 'limit', 'elite', 'exuberant', 'destruction', 'present'];

const result = words.filter(word => word.length > 6);

console.log(result); // ["exuberant", "destruction", "present"]

استخدام الدوال السهمية (ES6):

const words = ["spray", "limit", "elite", "exuberant", "destruction", "present", "happy"];

let longWords = words.filter(word => word.length > 6);

// ["exuberant", "destruction", "present"]

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

var newArray = arr.filter(callback[, thisArg])

callback

الدالة التي ستختبر كل عنصر من عناصر المصفوفة وستُعيد true إن أردنا الإبقاء على العنصر، و false إن شئنا حذفه، وتقبل ثلاثة وسائط.

currentValue

العنصر الحالي الذي يُعالِج في المصفوفة، وهذه القيمة مطلوبة.

index

فهرس العنصر الحالي في المصفوفة، وهذه القيمة اختيارية.

array

المصفوفة التي استدعيت الدالة every عليها، وهذه القيمة اختيارية.

thisArg

القيمة التي ستُستخدَم في this عند استدعاء الدالة callback، وهي قيمة اختيارية.

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

مصفوفة جديدة فيها العناصر التي نجحت في الاختبار.

الوصف

الدالة filter تُنفِّذ الدالة callback في كل عنصر موجود في المصفوفة، وتُنشِئ مصفوفةً جديدةً فيها جميع القيم التي تُعيد الدالةُ القيمةَ true عندها. لاحظ أنَّ الدالة callback ستُستدعى على الفهارس التي لها قيمٌ مسندةٌ إليها فقط، فهي لن تستدعى للفهارس التي حُذِفَت أو التي لم تُسنَد إليها قيم.

ستستدعى الدالة callback مع تمرير ثلاثة وسائط إليها: قيمة العنصر، وفهرسه، وكائن المصفوفة التي ستُختَبر عناصرها.

إذا وفّرنا المعامل thisArg إلى الدالة filter، فسيستخدم كقيمة this داخل الدالة callback، وإن لم نُحدِّد له قيمةً فستستعمل القيمة undefined.

لاحظ أنَّ الدالة filter لا تغيّر المصفوفة التي تستدعى عليها بأيّ شكلٍ من الأشكال.

أمثلة

ترشيح (حذف) القيم الصغيرة

المثال الآتي يستخدم الدالة filter لإنشاء مصفوفة جديدة لا تحتوي على أيّة عناصر أصغر من 10:

function isBigEnough(value) {
  return value >= 10;
}

var filtered = [12, 5, 8, 130, 44].filter(isBigEnough);
// [12, 130, 44]

ترشيح القيم غير الصالحة في صيغة JSON

المثال الآتي يستخدم الدالة filter لإنشاء مصفوفة فيه جميع العناصر التي لها قيمة رقمية للخاصية id:

var arr = [
  { id: 15 },
  { id: -1 },
  { id: 0 },
  { id: 3 },
  { id: 12.2 },
  { },
  { id: null },
  { id: NaN },
  { id: 'undefined' }
];

var invalidEntries = 0;

function isNumber(obj) {
  return obj!== undefined && typeof(obj) === 'number' && !isNaN(obj);
}

function filterByID(item) {
  if (isNumber(item.id)) {
    return true;
  } 
  invalidEntries++;
  return false; 
}

var arrByID = arr.filter(filterByID);

console.log('Filtered Array\n', arrByID); 
// المصفوفة الجديدة
// [{ id: 15 }, { id: -1 }, { id: 0 }, { id: 3 }, { id: 12.2 }]

console.log('Number of Invalid Entries = ', invalidEntries); 
// Number of Invalid Entries = 4

البحث في المصفوفة

المثال الآتي يوضِّح كيفية استخدام الدالة filter لترشيح مصفوفة بناءً على عبارة بحث:

var fruits = ['apple', 'banana', 'grapes', 'mango', 'orange'];

function filterItems(query) {
  return fruits.filter(function(el) {
      return el.toLowerCase().indexOf(query.toLowerCase()) > -1;
  })
}

console.log(filterItems('ap')); // ['apple', 'grapes']
console.log(filterItems('an')); // ['banana', 'mango', 'orange']

استخدام الدوال السهمية

يمكننا استخدام الدوال السهمية في المثال السابق لاختصار التعابير البرمجية:

const fruits = ['apple', 'banana', 'grapes', 'mango', 'orange'];

const filterItems = (query) => {
  return fruits.filter((el) =>
    el.toLowerCase().indexOf(query.toLowerCase()) > -1
  );
}

console.log(filterItems('ap')); // ['apple', 'grapes']
console.log(filterItems('an')); // ['banana', 'mango', 'orange']

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

أضيفت هذه الدالة في معيار ECMAScript 5، لذا يمكنك استخدام الشيفرة الآتية لإضافتها للمتصفحات التي لا تدعمها:

if (!Array.prototype.filter)
  Array.prototype.filter = function(func, thisArg) {
    'use strict';
    if ( ! ((typeof func === 'Function' || typeof func === 'function') && this) )
        throw new TypeError();
    
    var len = this.length >>> 0,
        res = new Array(len), // preallocate array
        t = this, c = 0, i = -1;
    if (thisArg === undefined)
      while (++i !== len)
        // checks to see if the key was set
        if (i in this)
          if (func(t[i], i, t))
            res[c++] = t[i];
    else
      while (++i !== len)
        // checks to see if the key was set
        if (i in this)
          if (func.call(thisArg, t[i], i, t))
            res[c++] = t[i];
    
    res.length = c; // shrink down array to proper size
    return res;
  };

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

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

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

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