jQuery/prop

يجلب هذا التابع قيمة خاصِّيَّة كائن محدَّدةٍ للعنصر الأول من مجموعة العناصر المطابقة، أو يضبط قيمة خاصِّيَّة كائن واحدة أو أكثر لجميع العناصر المطابقة.

‎.prop( propertyName )‎

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

يعيد أي شيء (وهو نوع افتراضي مُستخدَم في jQuery للإشارة إلى إمكانيَّة إعادة أي نوع).

الوصف

يجلب هذا التابع قيمة خاصِّيَّة كائن محدَّدةٍ للعنصر الأول من مجموعة العناصر المطابقة.

‎.prop( propertyName )‎

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

propertyName

سلسلة نصية تمثِّل اسم الخاصِّيَّة المراد إعادة قيمتها.

يجلب التابع ‎.prop()‎ قيمة خاصِّيَّة معينة للعنصر الأول فقط من مجموعة العناصر المطابقة. إن كانت الخاصِّيَّة غير مضبوطة بعد أو لم يكن هنالك أية عناصر في مجموعة العناصر المطابقة، فسيعيد التابع القيمة undefined. إن أردت جلب قيمة الخاصِّيَّة لكل عنصر في مجموعة العناصر المطابقة، فاستعمل إحدى البنى التكرارية في jQuery مثل التابع ‎.each()‎ أو التابع ‎.map()‎.

ملاحظة: سيؤدي محاولة تغيير قيمة الخاصِّيَّة type للعنصر <input> المنشأ حديثًا أو الموجود مسبقًا في مستند HTML إلى إصدار خطأ في المتصفح Internet Explorer ذي الإصدار 6 أو 7 أو 8.

الفرق بين خاصيات Attributes) HTML‎) وخاصيات الكائنات (Properties)

يكون الفرق بين خاصيّات HTML وخاصيّات الكائنات مهمًا في بعض الحالات. فكان التابع ‎.attr()‎ قبل الإصدار jQuery 1.6 يأخذ أحيانًا بالحسبان قيم خاصِّيَّات الكائنات عند محاولة الحصول على قيم بعض خاصِّيَّات HTML، ممّا قد يُسبِّب سلوكًا غير متناسق. بدءًا من الإصدار jQuery 1.6، أصبح التّابع ‎.prop()‎‎ يُزوِّدنا بطريقة للحصول على قيم خاصيّات الكائنات تحديدًا، بينما يعيد التّابعُ ‎.attr()‎ قيم خاصيّات HTML.

على سبيل المثال، ينبغي جلب قيمة خاصيّات الكائنات selectedIndex، و tagName، و nodeName، و nodeType، و ownerDocument، و defaultChecked، و defaultSelected عن طريق التابع ‎.prop()‎. قبل إصدار jQuery 1.6، كان من الممكن الحصول على قيمة خاصِّيَّات الكائنات هذه عبر التّابع ‎.attr()‎، ولكن لم يكن هذا من ضمن مجاله، فلا تملك خاصِّيَّات الكائنات هذه خاصَّيِّات HTML مُوافِقة لها وهي عبارة عن خاصِّيَّات للكائنات فقط.

فيما يتعلّق بخاصِّيَّات HTML المنطقيّة، فلنفترض وجود عنصر DOM مُعرَّف عن طريق عنصر HTML التالي:

<input type="checkbox" checked="checked">‎

ولنفترض أنّه ضمن متغيّر JavaScript يُدعى elem، فيكون ناتج الاستدعاءات التالية هو:

elem.checked‎	true (قيمة منطقيّة)، تتغيّر بحسب حالة صندوق التأشير.
‎$( elem ).prop( "checked" )‎	true (قيمة منطقيّة)، تتغيّر بحسب حالة صندوق التأشير.
‎elem.getAttribute( "checked" )‎	"checked" (سلسلة نصيّة)، الحالة المبدئيّة لصندوق التأشير، لا تتغيّر.
‎$( elem ).attr( "checked" )‎ (الإصدار 1.6)‏	"checked" (سلسلة نصيّة)، الحالة المبدئيّة لصندوق التأشير لا تتغيّر.
‎$( elem ).attr( "checked" )‎ (الإصدار 1.6.1+)‏	"checked" (سلسلة نصيّة)، تتغيّر بحسب حالة صندوق التأشير.
‎$( elem ).attr( "checked" )‎ (قبل الإصدار 1.6)‏	true (قيمة منطقيّة)، تتغيّر بحسب حالة صندوق التأشير.

وفقًا لمواصفة النماذج في W3C فإنّ خاصِّيَّة HTML ‏checked هي عبارة عن خاصِّيَّة منطقيّة (Boolean attribute)، ممّا يعني أنّ الخاصِّيَّة الكائنية الموافقة لها تكون قيمتها true بمجرّد وجود خاصِّيَّة HTML، حتى ولو لم تكن تملك أي قيمة أو كانت قيمتها سلسلة نصيّة فارغة، أو كانت قيمتها false، وينطبق هذا على جميع خاصِّيَّات HTML المنطقيّة.

على أيّة حال، أهم مفهوم يجب تذكره عن خاصِّيَّة HTML ‏checked أنّها لا تتوافق مع الخاصِّيَّة الكائنية checked، بل في الحقيقة تتوافق مع الخاصِّيَّة الكائنية defaultChecked ويجب أن تُستخدَم لتعيين القيمة الافتراضيّة لصندوق التأشير فلا تتغيّر خاصِّيَّة HTML ‏checked تبعًا لحالة صندوق التأشير بينما تتغيّر الخاصِّيَّة الكائنية checked بحسب حالته، لذلك فإنّ استخدام الخاصِّيَّة الكائنية هي الطريقة الأكثر توافقيّة عبر المتصفّحات لتحديد ما إذا كان صندوق التأشير مُحدَّدًا أم لا:

• if ( elem.checked )‎
• if ( $( elem ).prop( "checked" ) )‎
• if ( $( elem ).is( ":checked" ) )‎

وينطبق هذا على خاصِّيَّات HTML المتغيّرة الأخرى مثل selected و value.

ملاحظات إضافية

يؤدّي استخدام التّابع ‎.prop()‎ في متصفّح Internet Explorer قبل الإصدار التاسع لضبط الخاصِّيَّة الكائنية لعنصر DOM إلى أي شيء بخلاف قيمة أولية بسيطة (مثل عدد، أو سلسلة نصيّة، أو قيمة منطقيّة) إلى تسريب في الذاكرة (memory leak) إن لم تُزال الخاصِّيَّة الكائنية (باستخدام التّابع ‎.removeProp()‎) وذلك قبل إزالة عنصر DOM من المستند. ولتعيين قيم كائنات DOM بأمان دون حدوث تسريبات في الذّاكرة، استخدم التّابع ‎.data()‎.

أمثلة

عرض خاصِّيَّة HTML ‏checked والخاصِّيَّة الكائنية لمربع اختيار بينما تتغيّر قيمتها:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>prop مثالٌ عن استعمال التابع</title>
  <style>
  p {
    margin: 20px 0 0;
  }
  b {
    color: blue;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<input id="check1" type="checkbox" checked="checked">
<label for="check1">حدد صندوق التأشير</label>
<p></p>
 
<script>
$( "input" ).change(function() {
  var $input = $( this );
  $( "p" ).html(
    ".attr( \"checked\" ): <b>" + $input.attr( "checked" ) + "</b><br>" +
    ".prop( \"checked\" ): <b>" + $input.prop( "checked" ) + "</b><br>" +
    ".is( \":checked\" ): <b>" + $input.is( ":checked" ) + "</b>" );
}).change();
</script>
 
</body>
</html>

إن حُدِّد صندوق التأشير، فستكون النتيجة:

.attr( "checked" ): checked
.prop( "checked" ): true
.is( ":checked" ): true

أمَّا إن لم يحدَّد، فستكون النتيجة:

.attr( "checked" ): checked
.prop( "checked" ): false
.is( ":checked" ): false

prop( propertyName, value )‎.

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

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

الوصف

يضبط هذا التابع قيمة خاصِّيَّة كائن واحدة أو أكثر لمجموعة العناصر المُطابِقة.

prop( propertyName, value )‎.

أضيفت في الإصدار: 1.6.

propertyName

سلسلة نصيّة من الكائن String، وتمثِّل اسم الخاصِّيَّة الكائنية المطلوب تعيينها.

value

أي شيء (وهو نوع افتراضي مُستخدَم في jQuery للإشارة إلى إمكانيَّة استعمال أي نوع)، ويُمثِّل القيمة المطلوب تعيينها للخاصِّيَّة propertyName.

‎.prop( properties )‎

أضيفت في الإصدار: 1.6.

properties

كائن مُجرَّد (Object)، يمثّل أزواج خاصِّيَّة-قيمة المطلوب تعيينها.

‎.prop( propertyName, function )‎

أضيفت في الإصدار: 1.6.

propertyName

سلسلة نصيّة من الكائن String، تُمثِّل اسم خاصِّيَّة كائن المطلوب تعيينها.

function

دالة على الشكل Function( Integer index, Anything oldPropertyValue )‎، وتُعيد أي شيء. وهذه القيمة المُعادة ستُحدِّد ما هي القيمة المطلوب تعيينها، ويشير this إلى العنصر الحالي. تستقبل فهرس موقع العنصر في المجموعة والخاصِّيَّة الكائنية القديمة كوسائط لها.

يُعد التّابع ‎.prop()‎ طريقة مثاليّة لتعيين قيم خاصيّات الكائنات خاصّةً عند تعيين خاصِّيَّات متعدّدة، أو استخدام قيم مُعادَة من دالة ما، أو تعيين قيم خاصِّيَّات لعدَّة عناصر في الوقت ذاته. يجب استعمال هذا التابع لضبط قيم الخاصِّيَّات selectedIndex، و tagName، و nodeName، و nodeType، و ownerDocument، و defaultChecked، و defaultSelected. بدءًا من الإصدار jQuery 1.6، لم يعد بالإمكان ضبط هذه الخاصِّيَّات باستعمال التابع ‎.attr()‎، إذ لا تملك خاصِّيَّات HTML مقابلة وهي خاصِّيَّات كائنات فقط.

تؤثر خاصِّيَّات الكائنات عمومًا بالحالة الديناميكية للكائن DOM دون تغيير خاصِّيَّات HTML المتسلسلة، وهذا ينطبق مثلًا على الخاصِّيَّة value للعنصر <input>، أو الخاصِّيَّة disabled للعنصر <input> والعنصر <button>، أو الخاصِّيَّة checked في صندوق التأشير. بناءً على ذلك، إن أردت ضبط الخاصِّيَّة disabled والخاصِّيَّة checked، فاستعمل التابع ‎.prop()‎ وليس التابع ‎.attr()‎. يمكن أيضًا استعمال التابع ‎.val()‎ لجلب وضبط قيمة الخاصِّيَّات.

$( "input" ).prop( "disabled", false );
$( "input" ).prop( "checked", true );
$( "input" ).val( "someValue" );

ملاحظة مهمة: لا يجب استعمال التابع ‎.removeProp()‎ لضبط هذه قيمة الخاصِّيَّات إلى القيمة false. عندما تُزال الخاصِّيَّة الأساسيَّة، فلا يمكن إضافتها مجددًا. انظر صفحة التابع ‎.removeProp()‎ للمزيد من المعلومات.

قيم خاصيات الكائنات المحسوبة

يمكنك حساب قيمة الخاصِّيَّة عند استعمال دالةٍ لضبطها بناءً على قيم خاصِّيَّات أخرى للعنصر أو الخاصِّيَّة ذاتها المراد ضبطها. إن أردت مثلًا تبديل حالة مربعات الاختيار بناءً على قيمتها الحالية، فتفحَّص الشيفرة التالية:

$( "input[type='checkbox']" ).prop( "checked", function( i, val ) {
 return !val;
});

ملاحظة: إن لم تعيد الدالة التي يفترض بها أن تضبط قيمة الخاصِّيَّة (مثل الدالة function( index, prop ){})‎ في مثالنا) أي شيء أو أعادت القيمة undefined، فلن تتغير القيمة الحالية. هذا مفيد من أجل ضبط القيم انتقائيًّا عندما تتطابق معايير محدَّدة فقط.

ملاحظات إضافية

يؤدّي استخدام التّابع ‎.prop()‎ في متصفّح Internet Explorer قبل الإصدار التاسع إلى ضبط خاصِّيَّة كائن لعنصر DOM إلى أي شيء بخلاف قيمة أولية بسيطة (مثل عدد، أو سلسلة نصيّة، أو قيمة منطقيّة) إلى تسريب في الذاكرة (memory leak) إن لم تُزال الخاصِّيَّة الكائنية (باستخدام التّابع ‎.removeProp()‎) وذلك قبل إزالة عنصر DOM من المستند. ولتعيين قيم كائنات DOM بأمان دون حدوث تسريبات في الذّاكرة، استخدم التّابع ‎.data()‎.

أمثلة

تعطيل جميع مربعات الاختيار في الصفحة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>prop مثالٌ عن استعمال التابع</title>
  <style>
  img {
    padding: 10px;
  }
  div {
    color: red;
    font-size: 24px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
  <input type="checkbox" checked="checked">
  <input type="checkbox">
  <input type="checkbox">
  <input type="checkbox" checked="checked">
 
<script>
$( "input[type='checkbox']" ).prop({
  disabled: true
});
</script>
 
</body>
</html>

مصادر

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