التابع jQuery.extend() في jQuery
jQuery.extend( target [, object1 ] [, objectN ] )
القيم المعادة
يعيد كائنًا من النوع Object.
الوصف
يدمج هذا التابع محتويات عنصرين أو أكثر مع بعضهما بعضًا ويضع الناتج في الكائن الأول.
jQuery.extend( target [, object1 ] [, objectN ] )
أُضيف مع الإصدار: 1.0.
target
الكائن الذي سيضاف إليه خاصِّيَّات جديدة من الكائنات الأخرى إن مُرِّرت، أو سيوسِّع مجال أسماء jQuery (namespace) إن لم يُمرَّر سواه.
object1
كائن يحتوي على خاصِّيَّات إضافية يراد دمجها مع الكائن الأول target المعطى.
objectN
كائنات إضافيَّة تحتوي على خاصِّيَّات يراد دمجها مع الكائن الأول target المعطى.
jQuery.extend( [deep ], target, object1 [, objectN ] )
أُضيف مع الإصدار: 1.1.4.
deep
قيمة منطقيَّة (Boolean). إن كانت true، فسيصبح الدمج تكراريًّا (recursive يُعرَف أيضًا بالنسخ العميق [deep cope]) تمرير القيمة false إلى هذا الوسيط غير مدعوم بعد.
target
الكائن الذي سيضاف إليه خاصِّيَّات جديدة من الكائن أو الكائنات الأخرى المعطاة.
object1
كائن يحتوي على خاصِّيَّات إضافية يراد دمجها.
objectN
كائنات إضافيَّة تحتوي على خاصِّيَّات يراد دمجها.
عندما يمرَّر إلى التابع $.extend() كائنين أو أكثر، فستضاف جميع خاصِّيَّات الكائنات المعطاة إلى الكائن target. سيتم تجاهل الكائنات ذات القيمة العدميَّة (null) أو القيمة غير المُعرَّفة (undefined).
أمَّا إن مُرَّر إلى التابع $.extend() وسيط واحد، فهذا يعني أنَّ الوسيط target قد حُذِف. في هذه الحالة، سيُفترض أنَّ الكائن jQuery ذاته هو الوسيط target، وبذلك يمكن إضافة دوال جديدة إلى مجال أسماء jQuery. يمكن هذا أن يكون مفيدًا لمصممي الإضافات الذين يريدون إضافة توابع جديدة إلى jQuery.
تذكَّر دومًا أنَّ التابع $.extend() سيعدِّل الكائن target (الوسيط الأول) ثمَّ سيعيده. إن أردت الحفاظ على هذا الكائن من التعديل، فيمكنك فعل ذلك بتمرير كائن فارغ ليحل مكان الوسيط target:
var object = $.extend({}, object1, object2);
عمليَّة الدمج التي تجريها الدالة $.extend() غير تكراريَّة افتراضيًّا. إن كانت خاصِّيَّة الكائن الأول هي كائن أم مصفوفة بحد ذاتها، فستُستبدَل كاملًا، إذ سيحل مكانها المفتاح المماثل في الكائن الثاني أو الكائن اللاحق. لا تدمج القيم (values) مطلقًا، وهذا الأمر موضح في قسم الأمثلة في الأسفل. على أي حال، سيؤدي تمرير القيمة true إلى الوسيط الأول في الدالة إلى دمج الكائنات تكراريَّا.
تحذير: لا يدعم التابع استعمال القيمة false مع الوسيط deep؛ وإن مُرِّرت، فسيعدُّها التابع على أنَّها قيمة الوسيط target.
لن تُنسَخ الخاصِّيَّات ذات القيم غير المُعرَّفة (undefined). مع ذلك، ستنسخ القيم الموروثة من الخاصِّيَّة prototype. الخاصِّيَّات التي أنشأها الكائن عبر new MyCustomObject(args) أو المضمَّنة في أنواع JavaScript مثل Date أو RegExp لن يعاد إنشاؤها مجدَّدًا وستظهر كأنَّها كائنات عادية في الكائن أو المصفوفة المعادة.
عند استعمال القيمة true مع الوسيط deep، سيوسَّع الكائن والمصفوفة بينما لن يوسَّع الكائن الذي يغلِّف أحد الأنواع الأوليَّة مثل السلسلة النصية (String)، والقيمة المنطقيَّة (Boolean)، والأعداد (Number). بنية البيانات الدورية الممتدة بعمق ستؤدي إلى حدوث خطأ.
إن احتاج الأمر إلى تجاوز هذا السلوك، فاكتب تابع توسيع مخصَّص بدلًا من ذلك أو استعمل مكتبات أخرى مثل lodash.
أمثلة
دمج كائنين مع تعديل الكائن الأول:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.extend مثالٌ عن استعمال التابع</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="log"></div>
<script>
var object1 = {
apple: 0,
banana: { weight: 52, price: 100 },
cherry: 97
};
var object2 = {
banana: { price: 200 },
durian: 100
};
//object1 مع الكائن object2 دمج الكائن
$.extend( object1, object2 );
// IE<8 غير متاحة في JSON.stringify بفرض أن
$( "#log" ).append( JSON.stringify( object1 ) );
</script>
</body>
</html>
دمج كائنين بشكل تكراري مع تعديل الكائن الأول:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.extend مثالٌ عن استعمال التابع</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="log"></div>
<script>
var object1 = {
apple: 0,
banana: { weight: 52, price: 100 },
cherry: 97
};
var object2 = {
تفاح: { السعر: 200 },
durian: 100
};
// بشكل تكراري object1 مع الكائن object2 دمج الكائن
$.extend( true, object1, object2 );
// IE<8 غير متاحة في JSON.stringify بفرض أن
$( "#log" ).append( JSON.stringify( object1 ) );
</script>
</body>
</html>
دمج قيم افتراضيَّة مع الخيارات المقابلة لها دون تعديل القيم الافتراضيَّة. هذا المثال هو نموذج شائع لتطوير إضافة:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.extend مثالٌ عن استعمال التابع</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="log"></div>
<script>
var defaults = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
// دون تعديل القيم الافتراضية options مع الخيارات defaults دمج القيم الافتراضية
var settings = $.extend( {}, defaults, options );
// IE<8 غير متاحة في JSON.stringify بفرض أن
$( "#log" ).append( "<div><b>defaults -- </b>" + JSON.stringify( defaults ) + "</div>" );
$( "#log" ).append( "<div><b>options -- </b>" + JSON.stringify( options ) + "</div>" );
$( "#log" ).append( "<div><b>settings -- </b>" + JSON.stringify( settings ) + "</div>" );
</script>
</body>
</html>