jQuery/attr

يُستَخدَم التّابع ‎.attr()‎ للحصول على قيمة خاصيّة HTML لأوّل عنصر من مجموعة العناصر المُطابِقة، أو تعيين خاصيّة HTML أو عدة خاصيّات لكل عنصر مُطابِق.

attr( attributeName )‎.

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

سلسلة نصيّة على شكل الكائن String.

الوصف

الحصول على قيمة خاصيّة HTML لأوّل عنصر من مجموعة العناصر المُطابِقة.

attr( attributeName )‎.

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

attributeName

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

يحصل التّابع ‎.attr()‎ على قيمة خاصيّة HTML لأول عنصر فقط من المجموعة المُطابقة. للحصول على القيمة لكل عنصر على حدة، استخدم بُنية حلقيّة كتوابع jQuery مثل ‎.each()‎ أو ‎.map()‎.

يمتلك استخدام التابع ‎.attr()‎ في jQuery للحصول على قيمة خاصيّة العنصر فائدتين رئيسيتين:

1. السّهولة: من الممكن استدعاء هذا التّابع مباشرةً على كائن jQuery وبشكل سلسلة مع توابع jQuery الأخرى.
2. التّوافقيّة عبر المتصفّحات: ترد تقارير عن عدم توافقيّة قيم بعض خاصيّات HTML عبر المتصفّحات، وحتى عبر إصدارات المتصفّح ذاته. يُقلِّل التّابع ‎.attr()‎ من مشاكل عدم التوافقيّة هذه.

ملاحظة: قيم خاصيّات HTML هي سلاسل نصّيّة باستثناء بعض الخاصيّات مثل value وtabindex.

يُعيد التابع ‎.attr()‎ بدءًا من إصدار jQuery 1.6 القيمة undefined (غير مُعرَّف) لأجل خاصيّات HTML غير المُعيَّنة. للحصول على خاصيّات الكائن DOM وتغييرها مثل حالة عناصر الحقل checked، أو selected، أو disabled، فاستخدم التابع ‎.prop()‎.

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

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

على سبيل المثال ينبغي استرجاع خاصيّات الكائنات selectedIndex، و tagName، و nodeName، و nodeType، و ownerDocument، و defaultChecked، و defaultSelected عن طريق التابع ‎.prop()‎. قبل إصدار jQuery 1.6 كان من الممكن استرجاع خاصيّات الكائنات هذه عبر التّابع ‎.attr()‎، ولكن لم يكن هذا من ضمن مجال ‎.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>attr مثال عن التابع</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

إيجاد خاصيّة HTML للعنوان (title) لأول عنصر <em> في الصّفحة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>attr demo</title>
  <style>
  em {
    color: blue;
    font-weight: bold;
  }
  div {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>إيجاد قيمة خاصية العنوان <em title="huge, gigantic">لأول عنصر em</em> في الصفحة.</p>
 
عنوان عنصر em هو: <div></div>
 
<script>
var title = $( "em" ).attr( "title" );
$( "div" ).text( title );
</script>
 
</body>
</html>

تجربة المثال:

إيجاد قيمة خاصية العنوان لأول عنصر em في الصفحة:
عنوان عنصر em هو:
huge, gigantic

attr( attributeName, value )‎.

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

كائن jQuery.

الوصف

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

attr( attributeName, value )‎.

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

attributeName

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

value

سلسلة نصيّة أو عدد أو Null، وتُمثِّل القيمة المطلوب تعيينها لخاصيّة HTML، إن كانت null فستُزال خاصيّة HTML المُحدَّدة (كما يحدث عند استخدام التّابع ‎.removeAttr()‎).

attr( attributes )‎.

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

attributes

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

attr( attributeName, function )‎.

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

attributeName

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

function

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

يُعد التّابع ‎.attr()‎ طريقة مثاليّة لتعيين قيم خاصيّات HTML، خاصّةً عند تعيين خاصيّات متعدّدة أو استخدام قيم مُعادَة من دالة ما، فلنأخذ هذه الصّورة كمثال:

<img id="greatphoto" src="brush-seller.jpg" alt="brush seller">

تعيين خاصية HTML بسيطة

لتغيير الخاصيّة alt، مرِّر ببساطة اسمها وقيمتها الجديدة إلى التّابع ‎.attr()‎:

$( "#greatphoto" ).attr( "alt", "Beijing Brush Seller" );

أضف خاصيّة HTML جديدة للصورة بنفس الطريقة:

$( "#greatphoto" ).attr( "title", "Photo by Kelly Clark" );

تعيين خاصيات HTML متعددة بنفس الوقت

لتغيير الخاصيّة alt وإضافة الخاصيّة title بنفس الوقت، مرِّر اسمهما وقيمتهما إلى التّابع دفعةً واحدة باستخدام كائن JavaScript مُجرَّد، يُضيف كل زوج قيمة-مفتاح من الكائن خاصيّة HTML أو يُعدِّلها:

$( "#greatphoto" ).attr({

 alt: "Beijing Brush Seller",

 title: "photo by Kelly Clark"

});

عند تعيين قيم خاصيّات HTML متعدّدة يُصبح استخدام علامتي الاقتباس حول اسم خاصيّات HTML اختياريًّا.

تحذير: يجب استخدام علامات الاقتباس دومًا عند تعيين قيمة الخاصيّة class.

ملاحظة: تؤدّي محاولة تغيير الخاصيّة type للعنصرين input أو button المُنشَأين عبر document.createElement()‎ إلى رمي استثناء في إصدار Internet Explorer 8 فما قبل.

قيم خاصيات HTML المحسوبة

نستطيع باستخدام دالة لتعيين خاصيّات HTML أن نحسب القيمة بناءً على خصائص أخرى للعنصر، على سبيل المثال بإمكاننا جمع قيمة جديدة مع قيمة موجودة مُسبقًا:

$( "#greatphoto" ).attr( "title", function( i, val ) {

 return val + " - photo by Kelly Clark";

});

يكون استخدام الدالة لحساب قيم خاصيّات HTML مُفيدًا بشكل خاص عند تعديل خاصيّات HTML لعناصر متعدّدة معًا.

ملاحظة: إن لم تُرجِع دالة التعيين (أي function(index, attr){}‎) أي قيمة أو أعادت القيمة undefined، فالقيمة الحاليّة لم تتغيّر. يُفيدنا هذا لتعيين القيم بشكل انتقائي عند تحقّق معايير مُعيّنة فقط.

أمثلة

تعيين بعض خاصيّات HTML لكافة الصّور في الصّفحة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>attr مثال عن التابع</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>
 
<img>
<img>
<img>
 
<div><b>خاصيّات Ajax</b></div>
 
<script>
$( "img" ).attr({
  src: "/resources/hat.gif",
  title: "jQuery",
  alt: "jQuery Logo"
});
$( "div" ).text( $( "img" ).attr( "alt" ) );
</script>
 
</body>
</html>

تعيين المُعرِّف id لعناصر <div> بناءً على موقعها في الصّفحة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>attr مثال عن التابع</title>
  <style>
  div {
    color: blue;
  }
  span {
    color: red;
  }
  b {
    font-weight: bolder;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div>العنصر صفر <span></span></div>
<div>العنصر الأول <span></span></div>
<div>العنصر الثاني <span></span></div>
 
<script>
$( "div" )
  .attr( "id", function( arr ) {
    return "div-id" + arr;
  })
  .each(function() {
    $( "span", this ).html( "(id = '<b>" + this.id + "</b>')" );
});
</script>
 
</body>
</html>

تجربة المثال:

العنصر صفر (id = 'div-id0')
العنصر الأول (id = 'div-id1')
العنصر الثاني (id = 'div-id2')

تعيين خاصيّة src للصورة انطلاقًا من خاصيّة title لها:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>attr مثال عن التابع</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<img title="hat.gif">
 
<script>
$( "img" ).attr( "src", function() {
  return "/resources/" + this.title;
});
</script>
 
</body>
</html>

مصادر

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