التابع jQuery.param() في jQuery
jQuery.param( obj )
القيم المعادة
يعيد سلسلةً نصيةً (Array).
الوصف
يرمِّز (serialize) هذا التابع محتويات مصفوفة، أو كائن مجرَّد، أو كائن jQuery ويضعها في سلسلة نصيَّة لتصبح ملائمة لاستعمالها في سلسلة الاستعلام النصية لعنوان URL أو لإرسالها في طلبات Ajax. في حال تمرير كائن jQuery، فيجب أن يحوي هذا الكائن عناصر إدخال <input> لها خاصِّيَّات بالشكل اسم/قيمة.
jQuery.param( obj )
أُضيف مع الإصدار: 1.2.
obj
مصفوفة، أو كائن مجرَّد (Object)، أو كائن jQuery التي يراد ترميزها.
jQuery.param( obj, traditional )
أُضيف مع الإصدار: 1.4.
obj
مصفوفة، أو كائن مجرَّد (Object)، أو كائن jQuery التي يراد ترميزها.
traditional
قيمةٌ منطقيَّةٌ تحدِّد إن كان يُطلَب تنفيذ ترميز "سطحي" تقليدي.
يُستعمَل هذا التابع داخليًّا لتحويل قيم عنصر إلى سلسلة نصيَّة مرمَّزة (ارجع إلى صفحة التابع .serialize() للمزيد من المعلومات).
بدءًا من الإصدار jQuery 1.3، أصبح بالإمكان استعمال القيمة المعادة من دالةٍ بدلًا من استعمال الدالة كسلسلة نصيَّة.
بدءًا من الإصدار jQuery 1.4، أصبح بإمكان التابع $.parm() ترميز الكائنات العميقة (deep objects) بشكل تكراري للتوافق مع اللغات البرمجيَّة الحديثة وإطارات العمل (frameworks) مثل PHP و Ruby on Rails. تستطيع تعطيل هذه الوظيفة على الصعيد العام عبر jQuery.ajaxSettings.traditional = true;.
بدءًا من الإصدار jQuery 3.0، لم يعد يَستعمِل التابع $.parm() الضبط jQuery.ajaxSettings.traditional كضبط افتراضي خاص به، إذ ستكون القيمة الافتراضيَّة له هي false. للتخلص من مشكلة التوافقيَّة عبر الإصدارات، استَدعي التابع $.parm() مع تمرير قيمة الوسيط الثاني له بشكل صريح ولا تعتمد على القيمة الافتراضيَّة مطلقًا.
إن كان الوسيط الأول المُعطى مصفوفةً، فيجب أن تحتوي هذه المصفوفة على كائنات منسَّقة وفقًا للتنسيق المعاد بوساطة التابع .serializeArray():
[
{ name: "الاسم الأول", value: "سعيد" },
{ name: "الاسم الأخير", value: "البشير" },
{ name: "العمل", value: "لاعب ملاكمة" }
]
ملاحظة: بما أنَّ لبعض إطارات العمل قدرةٌ محدودةٌ على تحليل المصفوفات المرمَّزة، فيجب على المطورين توخي الحذر عند تمرير وسيط يحتوي على كائناتٍ أو مصفوفات متشعِّبة داخل مصفوفة أخرى.
ملاحظة: بما أنَّه لا يوجد معيارٌ عالميٌ متَّفقٌ عليه من أجل السلاسل النصيَّة التي يعيدها التابع $.param()، فمن غير الممكن ترميز بُنى بيانات معقَّدة باستعمال هذا التابع بطريقة يمكن استعمالها بشكل مثالي عبر جميع اللغات التي تدعم مثل هذه البيانات. ينصح باستعمال صيغة JSON كحل بديل لترميز بيانات معقَّدة.
في الإصدار jQuery 1.4، أصبح بالإمكان ترميز عناصر الإدخال <input> في HTML5.
يمكن إظهار سلسلة استعلام نصيَّة تمثل كائنًا، والنسخة غير المُرمَّزة من مكوِّن رابط URI المُرمَّز لنفس الكائن بالشكل التالي:
var myObject = {
a: {
one: 1,
two: 2,
three: 3
},
b: [ 1, 2, 3 ]
};
var recursiveEncoded = $.param( myObject );
var recursiveDecoded = decodeURIComponent( $.param( myObject ) );
alert( recursiveEncoded );
alert( recursiveDecoded );
ستظهر قيمة المتغيِّر recursiveEncoded والمتغيِّر recursiveDecoded بالشكل التالي:
a%5Bone%5D=1&a%5Btwo%5D=2&a%5Bthree%5D=3&b%5B%5D=1&b%5B%5D=2&b%5B%5D=3
a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3
لمحاكاة سلوك التابع $.parm() قبل الإصدار jQuery 1.4، يمكننا ضبط قيمة الوسيط traditional إلى القيمة true:
var myObject = {
a: {
one: 1,
two: 2,
three: 3
},
b: [ 1, 2, 3 ]
};
var shallowEncoded = $.param( myObject, true );
var shallowDecoded = decodeURIComponent( shallowEncoded );
alert( shallowEncoded );
alert( shallowDecoded );
ستظهر قيمة المتغيِّر shallowEncoded والمتغيِّر shallowDecoded بالشكل التالي:
a=%5Bobject+Object%5D&b=1&b=2&b=3
a=[object+Object]&b=1&b=2&b=3
أمثلة
ترميز كائن من مفتاح/قيمة:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.param مثالٌ عن استعمال التابع</title>
<style>
div {
color: red;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="results"></div>
<script>
var params = { width:1680, height:1050 };
var str = jQuery.param( params );
$( "#results" ).text( str );
</script>
</body>
</html>
ترميز بعض الكائنات المعقَّدة:
// <=1.3.2:
$.param({ a: [ 2, 3, 4 ] }); // "a=2&a=3&a=4"
// >=1.4:
$.param({ a: [ 2, 3, 4 ] }); // "a[]=2&a[]=3&a[]=4"
// <=1.3.2:
$.param({ a: { b: 1, c: 2 }, d: [ 3, 4, { e: 5 } ] });
// "a=[object+Object]&d=3&d=4&d=[object+Object]"
// >=1.4:
$.param({ a: { b: 1, c: 2 }, d: [ 3, 4, { e: 5 } ] });
// "a[b]=1&a[c]=2&d[]=3&d[]=4&d[2][e]=5"