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

يجلب هذا التابع محتوى HTML لأول عنصر في مجموعة العناصر المطابقة أو يغير محتوى HTML لكل العناصر المطابقة.

`()html.`

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

يعيد سلسلة نصية.

الوصف

يجلب هذا التابع محتوى HTML لأول عنصر في مجموعة العناصر المطابقة.

`‎.html()‎`

أضيفت مع الإصدار: 1.0، ولا يقبل هذا التابع أي معاملات.

هذا التابع غير متوافر في صفحات XML.

في صفحة HTML، يمكن استعمال التابع ()html. لجلب محتوى أي عنصر. إذا طابق تعبير المحدد أكثر من عنصر، فسيُعاد محتوى HTML للعنصر الأول فقط. لنفترض أنه لدينا الشيفرة التالية:

$( "div.demo-container" ).html();

للحصول على محتوى العنصر <div> الآتي، فيجب أن يكون أول عنصر <div> ويمتلك الصنف demo-container في الصفحة:

<div class="demo-container">
 <div class="demo-box">Demonstration Box</div>
</div>

النتيجة التي سنحصل عليها ستكون كالآتي :

<div class="demo-box">Demonstration Box</div>

يستعمل هذا التابع الخاصية innerHTML. يمكن ألا تعيد بعض المتصفحات محتوى HTML كما هو في الصفحة الأصلية. متصفح Internet Explorer يترك في بعض الأحيان علامات الاقتباس حول قيم الخاصيات إذا كانت تحتوي على أحرف أبجدية رقمية فقط على سبيل المثال.

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

الدالة jQuery أو أي تابع يقبل نص HTML كمعامل -مثل jQuery()‎ و ‎.append()‎ و ‎.after()‎ وغيرها- يمكنه تنفيذ شيفرات JavaScript. يمكن أن يحدث ذلك عبر حقن عناصر <script> أو استعمال خاصيات HTML التي تنفذ شيفرة معينة (مثل <img onload=""‎>). لا تستعمل هذه التوابع لإدخال النصوص التي حصلت عليها من مصادر غير موثوقة مثل معاملات استعلام الرابط URL، أو الكعكات، أو حقول الإدخال الخاصة بالنماذج (forms) وغيرها. القيام بشيء من هذا القبيل يمكن أن يشكل خطورة على سلامة الموقع. احذف أو هرّب (escape) أي معلومات مدخلة من قبل مستخدم معين قبل إضافة المحتوى إلى الصفحة.

أمثلة

الضغط على فقرة <p> يؤدي إلى إظهار شيفرة HTML الخاصة بها:

<!doctype html>
<html lang="en">
<head>
 <meta charset="utf-8">
 <title>html demo</title>
 <style>
 p {
   margin: 8px;
   font-size: 20px;
   color: blue;
   cursor: pointer;
 }
 b {
   text-decoration: underline;
 }
 button {
   cursor: pointer;
 }
 </style>
 <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p>
 <b>Click</b> to change the <span id="tag">html</span>
</p>
<p>
 to a <span id="text">text</span> node.
</p>
<p>
 This <button name="nada">button</button> does nothing.
</p>
<script>
$( "p" ).click(function() {
 var htmlString = $( this ).html();
 $( this ).text( htmlString );
});
</script>
</body>
</html>

`‎.html( htmlString )‎`

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

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

الوصف

يسند هذا التابع محتوى HTML لكل العناصر الموجودة في مجموعة العناصر المطابقة.

`‎.html(htmlString)‎`

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

`htmlString`

نص HTML، وهو النص الذي سيسند لكل العناصر المطابقة.

`‎.html(function)‎`

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

`Function`

دالة من الشكل Function( Number index, htmlString oldhtml )‎ والتي تعيد شيفرة HTML. ستُسنَد هذه الشيفرة إلى جميع العناصر المطابقة. تستقبل هذه الدالة فهرسًا يمثل موقع العنصر في المجموعة و تستقبل أيضًا نص HTML القديم. تفرِّغ jQuery العنصر المطابق قبل استدعاء الدالة. استعمل المعامل oldhtml للإشارة إلى المحتوى القديم، ويمكن استعمال this داخل الدالة للإشارة إلى العنصر المطابق.

التابع ()html. غير متوافر في صفحات XML.

عندما يُستعمل ()html. لتغيير محتوى العنصر، فسيزال المحتوى القديم كليًّا ويحل مكانه المحتوى الجديد. أضف إلى ذلك أنَّ jQuery تحذف البنيات الأخرى مثل البيانات (data) ومعالجات الأحداث (event handlers) من العناصر الأبناء قبل تبديل محتوى هذه العناصر مع المحتوى الجديد.

انظر إلى شيفرة HTML التالية:

<div class="demo-container">
 <div class="demo-box">Demonstration Box</div>
</div>

يمكن تغيير محتوى العنصر <div class="demo-container"‎> بالشكل التالي:

$( "div.demo-container" )
 .html( "<p>All new content. <em>You bet!</em></p>" );

الشيفرة السابقة ستبدل كل المحتوى داخل العنصر <div class="demo-container"‎>:

<div class="demo-container">
 <p>All new content. <em>You bet!</em></p>
</div>

يسمح لك التابع ()html. بدءًا من الإصدار jQuery 1.4 بتغيير محتوى HTML عبر تمرير دالة له مثل:

$( "div.demo-container" ).html(function() {
 var emphasis = "<em>" + $( "p" ).length + " paragraphs!</em>";
 return "<p>All new content for " + emphasis + "</p>";
});

لنفترض أنه لدينا صفحة بست فقرات، سيغير المثال أعلاه محتوى HTML للعنصر <div class="demo-container"‎> إلى <p>All new content for <em>6 paragraphs!</em></p>.

هذا التابع يستعمل خاصية المتصفح innerHTML. يمكن ألا تعيد بعض المتصفحات محتوى HTML كما هو في الصفحة الأصلية. قبل الإصدار 8 للمتصفح Internet Explorer مثلًا، كانت تُحول كل الخصائص href المطبقة على الروابط إلى روابط URL مطلقة. وقبل الإصدار 9 لذات المتصفح، لم يكن يتعامل يتعامل مع عناصر HTML5 بالشكل الصحيح بدون إضافة ما يسمى بطبقة التوافق (HTML5 Shiv).

لتغيير محتوى العنصر <script> الذي لا يحتوي على محتوى HTML، يجب استعمال التابع ‎.text()‎ وليس التابع ‎.html()‎.

ملاحظة: بدءًا من الإصدار 9 للمتصفح Internet Explorer، تغيير المحتوى النصي لعنصر HTML يمكن أن يفسد العقد النصية لأبنائه الذين حُذفوا من الصفحة نتيجة للعملية المنفذة. إذا كنت محتفظًا بمرجعية لعناصر DOM هذه وتريد أن تبقى هذه العناصر كما هي، فاستعمل ‎.empty().html( string )‎ بدلًا من ‎.html(string)‎ لحذف العناصر من الصفحة قبل إسناد النص الجديد للعنصر.

أمثلة

إضافة محتوى HTML لكل عنصر <div>:

<!doctype html>

<html lang="en">

<head>

<meta charset="utf-8">

<title>html demo</title>

<style>

.red {

  color: red;

}

</style>

<script src="https://code.jquery.com/jquery-1.10.2.js"></script>

</head>

<body>

<span>Hello</span>

<div></div>

<div></div>

<div></div>

<script>

$( "div" ).html( "<span class='red'>Hello <b>Again</b></span>" );

</script>

</body>

</html>

إضافة محتوى HTML لكل عنصر <div> وإضافة تغييرات على المحتوى المُدخل بعد ذلك مباشرةً:

<!doctype html>
<html lang="en">
<head>
 <meta charset="utf-8">
 <title>html demo</title>
 <style>
 div {
   color: blue;
   font-size: 18px;
 }
 </style>
 <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div></div>
<div></div>
<div></div>
<script>
$( "div" ).html( "<b>Wow!</b> Such excitement..." );
$( "div b" )
 .append( document.createTextNode( "!!!" ) )
 .css( "color", "red" );
</script>
</body>
</html>

مصادر

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