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

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

`jQuery.data( element, key, value )‎`

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

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

الوصف

يخزِّن هذا التابع بيانات اعتباطيَّة ويقرنها بعنصر محدَّد، ويعيد القيمة التي ضُبِطَت.

`jQuery.data( element, key, value )‎`

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

`element`

العنصر DOM الذي يراد ربط البيانات به.

`key`

سلسلة نصية تمثِّل الاسم الذي ستسمى البيانات المخزَّنة به.

`value`

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

ملاحظة: هذا التابع منخفض المستوى؛ يمكنك استعمال التابع ‎.data()‎ أيضًا إذ يُعدُّ ذا متسوًى مرتفع.

يسمح لنا التابع jQuery‎.data()‎ بإرفاق بيانات من أي نوع بعناصر DOM بطريقة آمنة من المراجع الدائرية (circular references) وبالتالي يقي من تسرُّب الذاكرة (memory leaks). تتأكد jQuery من حذف البيانات المرتبطة بالعنصر عند حذفه باستعمال توابع jQuery وعندما يغادر المستخدم الصفحة. يمكننا تعيين عدة قيم مميزة لعنصر واحد واستردادها لاحقًا:

jQuery.data( document.body, "foo", 52 );
jQuery.data( document.body, "bar", "test" );

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

لاحظ أنَّ هذا التابع لا يوفِّر حاليًا دعمًا عابرًا للمنصات لإعداد البيانات على مستندات XML، نظرًا لأنَّ المتصفح Internet Explorer لا يسمح بإرفاق البيانات عبر خصائص expando.
لا يمكن التعرف على النوع undefined كقيمة للبيانات. استدعاءات مثل jQuery‎.data( el, "name", undefined )‎ ستُعيد البيانات "name" المقابلة للعنصر el؛ أي هذا مماثلٌُ للاستدعاء jQuery.data( el, "name" )‎.

أمثلة

تخزين ثمَّ استدعاء قيمةٍ من العنصر <div>:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.data مثالٌ عن استعمال التابع</title>
  <style>
  div {
    color: blue;
  }
  span {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div>
  القيمة المخزَّنة هي
  <span></span>
  و
  <span></span>
</div>
 
<script>
var div = $( "div" )[ 0 ];
jQuery.data( div, "test", {
  first: 16,
  last: "أحمد"
});
$( "span:first" ).text( jQuery.data( div, "test" ).first );
$( "span:last" ).text( jQuery.data( div, "test" ).last );
</script>
 
</body>
</html>

`jQuery.data( element, key )‎`

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

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

الوصف

يعيد هذا التابع قطعة البيانات ذات الاسم المعطى والتي خُزِّنَت ورُبِطَت بعنصر معيَّن باستعمال jQuery.data(element, name, value)‎، أو يعيد جميع البيانات المُخزَّنة والمرتبطة بذلك العنصر.

`jQuery.data( element, key )‎`

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

`element`

العنصر DOM المراد إعادة البيانات المخزَّنة والمرتبطة به.

`key`

سلسلة نصية تمثل اسم قطعة البيانات المراد جلبها.

`jQuery.data( element )‎`

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

`element`

العنصر DOM المراد إعادة جميع البيانات المخزَّنة والمرتبطة به.

ملاحظة: هذا التابع منخفض المستوى؛ يمكنك استعمال التابع ‎.data()‎ أيضًا إذ يُعدُّ ذا متسوًى مرتفع.

لا يسترجع هذا التابع المنخفض المستوى البيانات المرتبطة بخاصِّيَّات data-* HTML5 إلا إذا استرجعها التابع ‎.data()‎ مسبقًا.

يسمح لنا التابع jQuery‎.data()‎ بإرفاق بيانات من أي نوع بعناصر DOM بطريقة آمنة من المراجع الدائرية (circular references) وبالتالي يقي من تسرُّب الذاكرة (memory leaks). تتأكد jQuery من حذف البيانات المرتبطة بالعنصر عند حذفه باستعمال توابع jQuery وعندما يغادر المستخدم الصفحة. يمكننا استرداد عدَّة قيم مميزة لعنصر واحد، واحدةً في كل استدعاء أو كمجموعة:

alert( jQuery.data( document.body, "foo" ) );
alert( jQuery.data( document.body ) );

تُنبِّه الشيفرة أعلاه قيم البيانات المخزَّنة للعنصر <body>. إذا لم تخزَّن أي بيانات لهذا العنصر، فستُعاد سلسلة نصية فارغة.

يسترجع التابع عند استدعائه بالشكل jQuery.data( element )‎ جميع القيم المرتبطة بالعنصر ككائن JavaScript. الجدير بالذكر أنَّ jQuery نفسها تستعمل هذا التابع لتخزين البيانات داخليًّا مثل معالجات الأحداث، لذا لا تتوقع وجود البيانات التي خزنتها أنت عبر شيفرتك فقط.

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

لاحظ أنَّ هذه الطريقة لا توفِّر حاليًا دعمًا عابرًا للمنصات لإعداد البيانات في مستندات XML، نظرًا لأن Internet Explorer لا يسمح بإرفاق البيانات عبر خاصَّيِّات expando.

أمثلة

الحصول على البيانات المسماة "blah" المُخزَّنة من أجل عنصر محدَّد:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.data مثالٌ عن استعمال التابع</title>
  <style>
  div {
    margin: 5px;
    background: yellow;
  }
  button {
    margin: 5px;
    font-size: 14px;
  }
  p {
    margin: 5px;
    color: blue;
  }
  span {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div>عنصر من النوع div</div>
<button>جلب البيانات “blah” للعنصر div</button>
<button>تخزين العبارة "مرحبًا" باسم "blah"</button>
<button>تخزين القيمة "86" باسم "blah"</button>
<button>حذف البيانات المسماة باسم “blah” المرتبطة بالعنصر div</button>
<p>قيمة البيانات ‘blah” المخزنة للعنصر div هي: <span>?</span></p>
 
<script>
$( "button" ).click( function() {
  var value,
    div = $( "div" )[ 0 ];
  switch ( $( "button" ).index( this ) ) {
  case 0 :
    value = jQuery.data( div, "blah" );
    break;
  case 1 :
    jQuery.data( div, "blah", "مرحبًا" );
    value = "تم التخزين";
    break;
  case 2 :
    jQuery.data( div, "blah", 86 );
    value = "تم التخزين";
    break;
  case 3 :
    jQuery.removeData( div, "blah" );
    value = "Removed!";
    break;
  }
  $( "span" ).text( "" + value );
});
</script>
 
</body>
</html>

مصادر

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