الفرق بين المراجعتين لصفحة: «jQuery/data»

المراجعة الحالية بتاريخ 13:00، 2 مايو 2018

يخزِّن التابع ‎.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>

مصادر

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

@@ سطر 1: / سطر 1: @@
-<noinclude>{{DISPLAYTITLE:التابع <code>.data()</code>‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ في jQuery}}</noinclude>
+<noinclude>{{DISPLAYTITLE:التابع <code>‎.data()‎</code> في jQuery}}</noinclude>
 يخزِّن التابع ‎<code>.data()‎</code> بيانات عشوائية مرتبطة بالعناصر المتطابقة أو تُعيد القيمة في مخزن البيانات المحدد للعنصر الأول في مجموعة العناصر المتطابقة.
@@ سطر 5: / سطر 5: @@
 === القيمة المعادة ===
-يعيد التابع ‎<code>.data()</code>‎ كائنًا من النوع [[wiki.hsoub.com/jQuery/jQuery|jQuery]]
+يعيد التابع ‎<code>.data()</code>‎ كائنًا من النوع [[jQuery/jQuery|jQuery]].
 === الوصف ===
@@ سطر 14: / سطر 14: @@
 ==== <code>key</code> ====
-سلسلة نصية مُنشَأة من الكائن [[JavaScript/String|String]]  تشير إلى جزء من البيانات المراد تعيينه.
+سلسلة نصية مُنشَأة من الكائن [[JavaScript/String|String]] تشير إلى جزء من البيانات المراد تعيينه.
 ==== <code>value</code> ====
-قيمة البيانات الجديدة، ويمكن أن تكون من أي نوع من أنواع JavaScript ما عدا النوع <code>undefined</code>.
+قيمة البيانات الجديدة، ويمكن أن تكون من أي نوع من أنواع JavaScript ما عدا القيمة <code>[[JavaScript/undefined|undefined]]</code>.
 === <code>‎.data( obj )‎</code> ===
@@ سطر 40: / سطر 40: @@
 غيَّر إصدار jQuery 3 سلوك هذا التابع لموافقة [https://www.w3.org/TR/html5/dom.html#dom-dataset مواصفات] Dataset API . على وجه التحديد، يُحوِّل الإصدار jQuery 3 كل تسلسل من حرفين من رمز "-" (U+002D) متبوعًا بحرف ASCII صغير إلى النسخة الكبيرة من نفس الحرف وفقًا لتعريف [https://www.w3.org/TR/html5/dom.html#dom-dataset خوارزمية] Dataset API. كتابة عبارة مثل ‎<code>$( "body" ).data( { "my-name": "aValue" } ).data();‎</code> سيؤدي إلى إعادة <code>{ myName: "aValue" }</code>.
-نظرًا للطريقة التي تتفاعل بها المتصفحات مع المكونات الإضافية والشيفرات الخارجية، لا يمكن استخدام التابع ‎<code>.data()‎</code> على العناصر <code><object></code> (ما لم يكن مكون فلاش إضافي Flash plugin) أو <code><applet></code> أو <code><embed></code>.
+نظرًا للطريقة التي تتفاعل بها المتصفحات مع المكونات الإضافية والشيفرات الخارجية، لا يمكن استخدام التابع ‎<code>.data()‎</code> على العناصر <code>[[HTML/object|<object>]]</code> (ما لم يكن مكون فلاش إضافي Flash plugin) أو <code><applet></code> أو <code>[[HTML/embed|<embed>]]</code>.
 === ملاحظات إضافية ===
 * لاحظ أن هذا التابع لا يوفر حاليًا دعمًا عابر للمنصات لإعداد البيانات على مستندات XML، نظرًا لأن Internet Explorer لا يسمح بإرفاق البيانات عبر خصائص expando.
-* لا يمكن التعرف على <code>undefined</code> كقيمة للبيانات. إستدعاءات مثل ‎<code>.data( "name", undefined )‎</code> ستُعيد كائن jQuery الذي أُستُدعِيَ، مما يسمح بالتسلسل.
+* لا يمكن التعرف على <code>[[JavaScript/undefined|undefined]]</code> كقيمة للبيانات. إستدعاءات مثل ‎<code>.data( "name", undefined )‎</code> ستُعيد كائن jQuery الذي أُستُدعِيَ، مما يسمح بالتسلسل.
 === أمثلة ===
-تخزين ثم استرجاع قيمة من عنصر div:<syntaxhighlight lang="jquery">
+تخزين ثم استرجاع قيمة من عنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code>:<syntaxhighlight lang="html">
 <!doctype html>
 <html lang="en">
@@ سطر 81: / سطر 81: @@
 </html>
 </syntaxhighlight>
-==== عرض تجريبي: ====
 == <code>‎.data( key )‎</code> ==
 === القيمة المعادة ===
-تُعيد قيمة من النوع [[JavaScript/Object|Object]]
+تُعيد قيمة من النوع [[JavaScript/Object|Object]].
 === الوصف ===
-تُعيد القيمة الموجودة في مخزن البيانات المحدد للعنصر الأول في مجموعة jQuery، كما هو محدد بواسطة data(name, value)‎ أو بأحد خاصيات data-*‎ في لغة HTML5.
+تُعيد القيمة الموجودة في مخزن البيانات المحدد للعنصر الأول في مجموعة jQuery، كما هو محدد بواسطة <code>data(name, value)</code>‎ أو بأحد خاصيات <code>data-*‎</code> في لغة HTML5.
 === <code>‎.data( key )‎</code> ===
@@ سطر 101: / سطر 99: @@
 أُضيفت مع إصدار: [http://api.jquery.com/category/version/1.4/ 1.4].
-لا يقبل هذا التوقيع أي وسائط.
+لا يقبل هذا الشكل أي وسائط.
 يسمح لنا التابع <code>‎.data()</code>‎ بإرفاق بيانات من أي نوع بعناصر DOM بطريقة آمنة من المراجع الدائرية (circular references) وبالتالي من تسرب الذاكرة (memory leaks). يمكننا استرداد عدة قيم مميزة لعنصر واحد، واحدة في كل مرة أو كمجموعة:<syntaxhighlight lang="jquery" start="1">
 alert( $( "body" ).data( "foo" ) );
 alert( $( "body" ).data() );
-</syntaxhighlight>تنبه الأسطر أعلاه قيم البيانات التي عُيِّن بها العنصر <code>body</code>. إذا لم تُعيَّن أي بيانات لهذا العنصر، فستُعاد القيمة <code>undefined</code>.<syntaxhighlight lang="jquery">
+</syntaxhighlight>تنبه الأسطر أعلاه قيم البيانات التي عُيِّن بها العنصر <code>[[HTML/body|<body>]]</code>. إذا لم تُعيَّن أي بيانات لهذا العنصر، فستُعاد القيمة <code>[[JavaScript/undefined|undefined]]</code>.<syntaxhighlight lang="jquery">
 alert( $( "body" ).data( "foo" ) ); // undefined
 $( "body" ).data( "bar", "foobar" );
 alert( $( "body" ).data( "bar" ) ); // foobar
-</syntaxhighlight>غيَّر إصدار jQuery 3 سلوك هذا التابع لموافقة [https://www.w3.org/TR/html5/dom.html#dom-dataset مواصفات] Dataset API . على وجه التحديد، يُحوِّل الإصدار jQuery 3 كل تسلسل من حرفين من رمز "-" (U+002D) متبوعًا بحرف ASCII صغير إلى النسخة الكبيرة من ذات الحرف وفقًا لتعريف [https://www.w3.org/TR/html5/dom.html#dom-dataset خوارزمية] Dataset API . كتابة عبارة مثل <code>‎$( "body" ).data( { "my-name": "aValue" } ).data();</code>‎ سيؤدي إلى إعادة <code>{ myName: "aValue" }</code>.
+</syntaxhighlight>غيَّر إصدار jQuery 3 سلوك هذا التابع لموافقة [https://www.w3.org/TR/html5/dom.html#dom-dataset مواصفات Dataset API]. على وجه التحديد، يُحوِّل الإصدار jQuery 3 كل تسلسل من حرفين من رمز "-" (U+002D) متبوعًا بحرف ASCII صغير إلى النسخة الكبيرة من ذات الحرف وفقًا لتعريف [https://www.w3.org/TR/html5/dom.html#dom-dataset خوارزمية Dataset API]. كتابة عبارة مثل <code>‎$( "body" ).data( { "my-name": "aValue" } ).data();</code>‎ سيؤدي إلى إعادة <code>{ myName: "aValue" }</code>.
-==== خاصيات data-*‎ في HTML5 ====
+==== خاصيات <code>data-*</code>‎ في HTML5 ====
 بدءًا من jQuery 1.4.3، ستُستخدم خاصيات [https://johnresig.com/blog/html-5-data-attributes/ بيانات HTML5] تلقائيًا ككائن بيانات jQuery. وتغيرت معاملة الخاصيات ذات الشرطات المدمجة في jQuery 1.6 لتتوافق مع [https://www.w3.org/TR/html5/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes مواصفة HTML5].
 على سبيل المثال، في شيفرة HTML التالية:<syntaxhighlight lang="jquery">
 <div data-role="page" data-last-value="43" data-hidden="true" data-options='{"name":"John"}'></div>
-</syntaxhighlight>ستعمل كل شيفرات jQuery التالية.<syntaxhighlight lang="jquery">
+</syntaxhighlight>ستعمل كل شيفرات jQuery التالية:<syntaxhighlight lang="jquery">
 $( "div" ).data( "role" ) === "page";
 $( "div" ).data( "lastValue" ) === 43;
@@ سطر 126: / سطر 124: @@
 تجري كل محاولة بهدف تحويل السلسلة النصية إلى قيمة JavaScript (بما في ذلك [[JavaScript/Boolean|القيم المنطقية]]، و<nowiki/>[[JavaScript/Number|الأرقام]]، و<nowiki/>[[JavaScript/Object|الكائنات]]، و<nowiki/>[[JavaScript/Array|المصفوفات]]، و<nowiki/>[[JavaScript/null|القيم الفارغة null]]). تُحول القيمة إلى رقم فقط إذا كان ذلك لا يؤدي إلى تغيير تمثيل القيمة. على سبيل المثال، تتعادل "1E02" و "100.000" كأرقام (قيمة رقمية 100) ولكن تحويلهما سيغير تمثيلهما بحيث تُتركان كسلسلتان نصيتان. وتتحول قيمة السلسلة "100" إلى الرقم 100.
-عندما تكون خاصية البيانات كائنًا (يبدأ بالرمز ‎'{'‎) أو مصفوفةً (تبدأ بالرمز ‎'['‎)، فسيستخدم التابع <code>jQuery.parseJSON</code> لتحليل السلسلة النصية؛ يجب أن تتبع [[wikipedia:JSON#Data_types.2C_syntax_and_example|صيغة جملة JSON صالحة]] بما في ذلك أسماء الخاصيات المقتبسة. إذا لم تكن القيمة قابلة للتحويل كقيمة JavaScript، فستُترك كسلسلة نصية.
+عندما تكون خاصية البيانات كائنًا (يبدأ بالرمز ‎'<code>{</code>'‎) أو مصفوفةً (تبدأ بالرمز ‎'<code>[</code>'‎)، فسيستخدم التابع <code>[[jQuery/jQuery/parseJSON|jQuery.parseJSON]]</code> لتحليل السلسلة النصية؛ يجب أن تتبع [[wikipedia:JSON#Data_types.2C_syntax_and_example|صيغة جملة JSON صالحة]] بما في ذلك أسماء الخاصيات المقتبسة. إذا لم تكن القيمة قابلة للتحويل كقيمة JavaScript، فستُترك كسلسلة نصية.
-للحصول على قيمة خاصيةٍ ما كسلسلة نصية بدون أي محاولة لتحويلها، استخدم طريقة <code>attr‎()‎</code>.
+للحصول على قيمة خاصيةٍ ما كسلسلة نصية بدون أي محاولة لتحويلها، استخدم التابع <code>[[jQuery/attr|attr‎()‎.]]</code>.
 تُسحب خواص البيانات في المرة الأولى التي يُوصل فيها إلى خاصية البيانات ثم لا يمكن الوصول إليها أو تُحوَّر (تُخزَّن جميع قيم البيانات داخليًا في jQuery).
@@ سطر 144: / سطر 142: @@
 === أمثلة ===
-الحصول على البيانات المسماة "blah" المخزنة في عنصر.<syntaxhighlight lang="jquery">
+الحصول على البيانات المسماة <code>"blah"</code> المخزنة في عنصر.<syntaxhighlight lang="html">
 <!doctype html>
 <html lang="en">
@@ سطر 207: / سطر 205: @@
 </html>
 </syntaxhighlight>
-==== عرض تجريبي: ====
 == مصادر ==
 * [http://api.jquery.com/data/ صفحة التابع ‎.data()‎ في توثيق jQuery الرسمي].
 [[تصنيف:jQuery]]
+[[تصنيف:jQuery Method]]
+[[تصنيف:jQuery Data]]