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

من موسوعة حسوب

يخزِّن التابع ‎.data()‎ بيانات عشوائية مرتبطة بالعناصر المتطابقة أو تُعيد القيمة في مخزن البيانات المحدد للعنصر الأول في مجموعة العناصر المتطابقة.

‎.data( key, value )‎

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

يعيد التابع ‎.data()‎ كائنًا من النوع jQuery.

الوصف

يُخزن بيانات عشوائية مرتبطة بالعناصر المتطابقة.

‎.data( key, value )‎

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

key

سلسلة نصية مُنشَأة من الكائن String تشير إلى جزء من البيانات المراد تعيينه.

value

قيمة البيانات الجديدة، ويمكن أن تكون من أي نوع من أنواع JavaScript ما عدا القيمة undefined.

‎.data( obj )‎

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

obj

كائن من النوع Object يحتوي على أزواج المفاتيح والقيم للبيانات المراد تحديثها.

يسمح لنا التابع ‎.data()‎ بإرفاق بيانات من أي نوع بعناصر DOM بطريقة آمنة من المراجع الدائرية (circular references) وبالتالي يقي من تسرب الذاكرة (memory leaks).

يمكننا تعيين عدة قيم مميزة لعنصر واحد واستردادها لاحقًا:

$( "body" ).data( "foo", 52 );
$( "body" ).data( "bar", { myType: "test", count: 40 } );
$( "body" ).data( { baz: [ 1, 2, 3 ] } );
$( "body" ).data( "foo" ); // 52
$( "body" ).data(); // { foo: 52, bar: { myType: "test", count: 40 }, baz: [ 1, 2, 3 ] }

تعيين كائن بيانات عنصر بواسطة ‎.data(obj)‎ في إصدار jQuery 1.4.3 يوسِّع البيانات المخزنة مسبقًا مع هذا العنصر.

قبل jQuery 1.4.3 (بدءًا من jQuery 1.4) يُبدِّل التابع ‎.data()‎ جميع البيانات بالكامل، بدلاً من مجرد توسيع كائن البيانات. إذا كنت تستخدم مكونات إضافية تابعة لجهة خارجية، قد لا يكون من المستحسن استبدال كائن بيانات العنصر بالكامل، نظرًا لأن المكوّنات الإضافية قد تكون قد عيَّنت بيانات أيضًا.

غيَّر إصدار jQuery 3 سلوك هذا التابع لموافقة مواصفات Dataset API . على وجه التحديد، يُحوِّل الإصدار jQuery 3 كل تسلسل من حرفين من رمز "-" (U+002D) متبوعًا بحرف ASCII صغير إلى النسخة الكبيرة من نفس الحرف وفقًا لتعريف خوارزمية Dataset API. كتابة عبارة مثل ‎$( "body" ).data( { "my-name": "aValue" } ).data();‎ سيؤدي إلى إعادة { myName: "aValue" }.

نظرًا للطريقة التي تتفاعل بها المتصفحات مع المكونات الإضافية والشيفرات الخارجية، لا يمكن استخدام التابع ‎.data()‎ على العناصر <object> (ما لم يكن مكون فلاش إضافي Flash plugin) أو <applet> أو <embed>.

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

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

أمثلة

تخزين ثم استرجاع قيمة من عنصر <div>:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>data demo</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>
$( "div" ).data( "test", { first: 16, last: "pizza!" } );
$( "span:first" ).text( $( "div" ).data( "test" ).first );
$( "span:last" ).text( $( "div" ).data( "test" ).last );
</script>
 
</body>
</html>

‎.data( key )‎

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

تُعيد قيمة من النوع Object.

الوصف

تُعيد القيمة الموجودة في مخزن البيانات المحدد للعنصر الأول في مجموعة jQuery، كما هو محدد بواسطة data(name, value)‎ أو بأحد خاصيات data-*‎ في لغة HTML5.

‎.data( key )‎

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

key

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

‎.data()‎

أُضيفت مع إصدار: 1.4.

لا يقبل هذا الشكل أي وسائط.

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

alert( $( "body" ).data( "foo" ) );
alert( $( "body" ).data() );

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

alert( $( "body" ).data( "foo" ) ); // undefined
$( "body" ).data( "bar", "foobar" );
alert( $( "body" ).data( "bar" ) ); // foobar

غيَّر إصدار jQuery 3 سلوك هذا التابع لموافقة مواصفات Dataset API. على وجه التحديد، يُحوِّل الإصدار jQuery 3 كل تسلسل من حرفين من رمز "-" (U+002D) متبوعًا بحرف ASCII صغير إلى النسخة الكبيرة من ذات الحرف وفقًا لتعريف خوارزمية Dataset API. كتابة عبارة مثل ‎$( "body" ).data( { "my-name": "aValue" } ).data();‎ سيؤدي إلى إعادة { myName: "aValue" }.

خاصيات data-*‎ في HTML5

بدءًا من jQuery 1.4.3، ستُستخدم خاصيات بيانات HTML5 تلقائيًا ككائن بيانات jQuery. وتغيرت معاملة الخاصيات ذات الشرطات المدمجة في jQuery 1.6 لتتوافق مع مواصفة HTML5.

على سبيل المثال، في شيفرة HTML التالية:

<div data-role="page" data-last-value="43" data-hidden="true" data-options='{"name":"John"}'></div>

ستعمل كل شيفرات jQuery التالية:

$( "div" ).data( "role" ) === "page";
$( "div" ).data( "lastValue" ) === 43;
$( "div" ).data( "hidden" ) === true;
$( "div" ).data( "options" ).name === "John";

تشير العبارة الثانية من الشيفرة البرمجية أعلاه بشكل صحيح إلى الخاصية data-last-value للعنصر. في حالة عدم تخزين أية بيانات مع المفتاح المُمرَّر، تبحث jQuery بين خاصيات العنصر، ويحول سلسلة ذات أحرف أولى كبيرة إلى سلسلة متقطعة ثم يرفق بادِئة data-‎ إلى النتيجة. وهكذا، تتحول السلسلة lastValue إلى data-last-value.

تجري كل محاولة بهدف تحويل السلسلة النصية إلى قيمة JavaScript (بما في ذلك القيم المنطقية، والأرقام، والكائنات، والمصفوفات، والقيم الفارغة null). تُحول القيمة إلى رقم فقط إذا كان ذلك لا يؤدي إلى تغيير تمثيل القيمة. على سبيل المثال، تتعادل "1E02" و "100.000" كأرقام (قيمة رقمية 100) ولكن تحويلهما سيغير تمثيلهما بحيث تُتركان كسلسلتان نصيتان. وتتحول قيمة السلسلة "100" إلى الرقم 100.

عندما تكون خاصية البيانات كائنًا (يبدأ بالرمز ‎'{'‎) أو مصفوفةً (تبدأ بالرمز ‎'['‎)، فسيستخدم التابع jQuery.parseJSON لتحليل السلسلة النصية؛ يجب أن تتبع صيغة جملة JSON صالحة بما في ذلك أسماء الخاصيات المقتبسة. إذا لم تكن القيمة قابلة للتحويل كقيمة JavaScript، فستُترك كسلسلة نصية.

للحصول على قيمة خاصيةٍ ما كسلسلة نصية بدون أي محاولة لتحويلها، استخدم التابع attr‎()‎..

تُسحب خواص البيانات في المرة الأولى التي يُوصل فيها إلى خاصية البيانات ثم لا يمكن الوصول إليها أو تُحوَّر (تُخزَّن جميع قيم البيانات داخليًا في jQuery).

استدعاء ‎.data()‎ بدون أي معاملات يستخرج كافة القيم ككائن JavaScript. ويُمكن تخزين هذا الكائن بأمان مؤقتًا في متغير طالما لم يُضبَط كائن جديد بواسطة ‎.data(obj)‎ . ويعد استخدام الكائن مباشرة للحصول على القيم أو تعيينها أسرع من إجراء استدعاءات فردية للتابع ‎.data()‎ للحصول على كل قيمة أو تعيينها:

var mydata = $( "#mydiv" ).data();
if ( mydata.count < 9 ) {
  mydata.count = 43;
  mydata.status = "embiggened";
}

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

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

أمثلة

الحصول على البيانات المسماة "blah" المخزنة في عنصر.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>data demo</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>A div</div>
<button>Get "blah" from the div</button>
<button>Set "blah" to "hello"</button>
<button>Set "blah" to 86</button>
<button>Remove "blah" from the div</button>
<p>The "blah" value of this div is <span>?</span></p>
 
<script>
$( "button" ).click(function() {
  var value;
 
  switch ( $( "button" ).index( this ) ) {
    case 0 :
      value = $( "div" ).data( "blah" );
      break;
    case 1 :
      $( "div" ).data( "blah", "hello" );
      value = "Stored!";
      break;
    case 2 :
      $( "div" ).data( "blah", 86 );
      value = "Stored!";
      break;
    case 3 :
      $( "div" ).removeData( "blah" );
      value = "Removed!";
      break;
  }
 
  $( "span" ).text( "" + value );
});
</script>
 
</body>
</html>

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=jQuery/data&oldid=7293»