التابع `‎‎.map()‎`‎ في jQuery

`‎.map( callback )‎`

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

يعيد كائنًا من النوع jQuery.

الوصف

يمرِّر هذا التابع كل عنصر من عناصر المجموعة الحالية إلى دالة، وينشئ كائنًا جديدًا من النوع jQuery يحتوي على القيم المعادة.

`‎.map( callback )‎`

أُضيف مع الإصدار: 1.2.

`callback`

دالة من الشكل Function( Number index, Element domElement )‎ التي ستُستدعى لكل عنصر في المجموعة الحالية.

إن أردت معالجة مصفوفة أو كائن مجرد، فاستعمل jQuery.map()‎ بدلًا من هذا التابع.

لما كانت القيمة المعادة كائنًا مجردًا يحتوي على مصفوفة، فمن الشائع استعمال التابع ‎.get()‎ معه للتعامل مع تلك المصفوفة.

التابع ‎.map()‎ مفيد خصوصًا في جلب أو ضبط قيمة مجموعة من العناصر. افترض وجود نموذج يحتوي على مجموعة من مربعات الاختيار مثل:

<form method="post" action="">
  <fieldset>
    <div>
      <label for="two">2</label>
      <input type="checkbox" value="2" id="two" name="number[]">
    </div>
    <div>
      <label for="four">4</label>
      <input type="checkbox" value="4" id="four" name="number[]">
    </div>
    <div>
      <label for="six">6</label>
      <input type="checkbox" value="6" id="six" name="number[]">
    </div>
    <div>
      <label for="eight">8</label>
      <input type="checkbox" value="8" id="eight" name="number[]">
    </div>
  </fieldset>
</form>

توضح الشيفرة التالية كيفية جلب قائمة مفصولة بفاصلة تحتوي على معرفات (ID) صناديق الاختيار:

$( ":checkbox" )
  .map(function() {
    return this.id;
  })
  .get()
  .join();

ستكون النتيجة هي السلسلة النصية: "two,four,six,eight".

تشير this ضمن دالة رد النداء إلى عنصر DOM الحالي لكل تكرار. يمكن للدالة أن تعيد عنصر واحد من البيانات أو مصفوفة من العناصر تحتوي على البيانات لتُدرج ضمن المجموعة الناتجة. إن أُعيدت مصفوفة، فستدرج عناصر تلك المصفوفة إلى المجموعة. إن أعادت الدالة القيمة null أو القيمة undefined، فلن يُدرج أي عنصر.

أمثلة

مثال عن إنشاء قائمة من جميع القيم المدخلة إلى نموذج:

<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>map مثالٌ عن استعمال التابع</title>
  <style>
  p {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p><b>القيم: </b></p>
<form>
  <input type="text" name="name" value="بشير">
  <input type="text" name="password" value="كلمة المرور">
  <input type="text" name="url" value="https://bashiresig.com/">
</form>
 
<script>
$( "p" )
  .append( $( "input" ).map(function() {
    return $( this ).val();
  })
  .get()
  .join( ", " ) );
</script>
 
</body>
</html>

مثال رائع يظهر بعض وظائف التابع ‎.map()‎:

<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>map مثالٌ عن استعمال التابع</title>
  <style>
  body {
    font-size: 16px;
  }
  ul {
    float: left;
    margin: 0 30px;
    color: blue;
  }
  #results {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<ul>
  <li>الأول</li>
  <li>الثاني</li>
  <li>الثالث</li>
  <li>الرابع</li>
  <li>الخامس</li>
</ul>
<ul id="results">
</ul>
 
<script>
var mappedItems = $( "li" ).map(function( index ) {
  var replacement = $( "<li>" ).text( $( this ).text() ).get( 0 );
  if ( index === 0 ) {
 
    // جعل أحرف العنصر الأول كبيرة
    $( replacement ).text( $( replacement ).text().toUpperCase() );
  } else if ( index === 1 || index === 3 ) {
 
    // حذف العنصر الثاني والرابع
    replacement = null;
  } else if ( index === 2 ) {
 
    // تكرار العنصر الثالث وإضافة نص زائد إليه
    replacement = [ replacement, $( "<li>" ).get( 0 ) ];
    $( replacement[ 0 ] ).append( "<b> - A</b>" );
    $( replacement[ 1 ] ).append( "Extra <b> - B</b>" );
  }
 
  // null أو القيمة DOM سيكون عنصر replacment المتغير
  // DOM أو مصفوفة من عناصر
});
$( "#results" ).append( mappedItems );
</script>
 
</body>
</html>

مثال يوضح كيفية مساواة ارتفاع جميع العناصر <div>:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>map demo</title>
  <style>
  div {
    width: 40px;
    float: left;
  }
  input {
    clear: left;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<input type="button" value="equalize div heights">
<div style="background: red; height: 40px; "></div>
<div style="background: green; height: 70px;"></div>
<div style="background: blue; height: 50px; "></div>
 
<script>
$.fn.equalizeHeights = function() {
  var maxHeight = this.map(function( i, e ) {
    return $( e ).height();
  }).get();
  return this.height( Math.max.apply( this, maxHeight ) );
};
 
$( "input" ).click(function() {
  $( "div" ).equalizeHeights();
});
</script>
 
</body>
</html>

مصادر

صفحة التابع ‎‎.map()‎ في توثيق jQuery الرسمي.